Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including gulp-i18n-extract with all npm packages installed. Try it out:

var gulpI18nExtract = require("gulp-i18n-extract")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

gulp-i18n-extract v1.0.13

Extracts I18N data from html pages.


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


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free