Skip to content
This gulp tasks extracts i18n keys and texts from HTML and JSON files.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


NPM version

This gulp tasks extracts i18n keys and texts from HTML and JSON files.

This task ist part of the i18n toolchain:

  1. [Tag](to be implemented) text nodes in HTML with an i18n key attribute
  2. Extract i18n keys and values (This task)
  3. Translate
  4. Compile into language files for i18n like Aurelia-i18n


Install gulp-i18n-extract using npm into your local repository.

npm install gulp-i18n-extract --save-dev


Setup a gulp task i18n-extract. By default, this job will only extract data from html files.

var gulp = require('gulp');
var i18n = require('gulp-i18n-extract');

var options = {};

gulp.task('i18n-extract', function() {
  return gulp.src("src/**/*.html")


  • outFile : string = 'i18nextract.json'

    Output file name.

  • plugIns : object[] = [ new i18n.html("t") ]

    Specify, which plug-in should be used on extraction.

  • markUpdates : boolean = true

    If an extracted value has been changed or added, it will be marked with "needsUpdate":true .

  • defaultLanguages : string[] = ["de"]

    Each default language will be added as translation, if missing.

  • warnOnDuplicates : boolean = true

    Created warnings if i18n keys are used twice.

  • keepObsoleteTranslations : boolean = 'false'

    All translations from obsolete or deleted key will remain in the extract file as obsoleteTranslations. These texts will be grouped by the extracted content and contain all found translations.

##Output structure

	"<filename w/o ext>": {
		"src":"<relative file path>",
		"content": {
			"<i18n key>": {
				"content":"<extracted content>",
				"lastModified":"<date of extraction>",
				"translations": {
					"<language, 2letter iso>" : {
						"content":"<translated content>",
						"lastModified":"<date of translation>"
	"obsoleteTranslations": [
			"key":"<original text>",
				"<language, 2letter iso>": [
					"<found translation for original text>",
					"<found translation for original text>",


There are two predefined plugins available to handle html and json files.


You can specify the attribute that is used to identify localizable strings. (Default: "t")

var options = { plugIns:[ new i18n.html("t") ] };  


  • Extract the inner text
<h1 t="index.title">Welcome</h1>
  • Extract attributes
<input type="email" placeholder="Email" t="[placeholder]">
  • Inner text and attributes
<span data-toggle="tooltip" data-placement="right" title="Tooltip" 
	  Example text
  • Skip extraction of certain keys by providing ignore function in the second argument. In the following example, index.${variable} is not extracted.
var options = { plugIns:[ new i18n.html("t", (key) => key.indexOf("${") >= 0) ] };  
<input type="email" placeholder="Ignored for extraction" t="[placeholder]index.${variable}">


You can specify the file extension for your json files. (Default: ".r.json")

var options = { plugIns:[ new i18n.json(".r.json") ] }; 	  

Custom PlugIn

A plugin has to provide two functions: canHandle and parse.

canHandle will be called to determine, if the plugin can extract tokens out of the given file.

parse implements the extraction and will receive the file and an addToken function.

var customPlugIn = {		
		canHandle : function(fileName) {			
			return true || false;
		parse: function (file, addToken) {			
			addToken("i18nKey","extracted text");					
var options = { plugIns:[ customPlugIn ] }; 


Apache 2.0

You can’t perform that action at this time.