Static Internationalization

Gulp plugin to translate static assets.

Install

$ npm install --save-dev gulp-static-i18n

Usage

Example gulp file:

'use strict';
var gulp = require('gulp');
var del = require('del');
var statici18n = require('gulp-static-i18n');

gulp.task('clean', function(cb) {
  del(['build'], cb);
});

gulp.task('build', gulp.series('clean', function(){
  return gulp.src(['src/**'])
    .pipe(gulp.dest('build'));
}));

gulp.task('translate', gulp.series('build', function(){
  return gulp.src(['build'])
    .pipe(statici18n());
}));

module.exports = gulp;

Creating Language Builds

statici18n consumes source files and puts out versions in each language present in the canonical locale directory, organized in their own sub-directories.

Example:

Source

app
├── index.html
├── script.js // alert(gettext("Hello World"));
└── locale
    ├── fr
    └── pt_BR

Build

app
├── build
│   ├── index.html
│   └── script.js  // alert(gettext("Hello World"));
├── index.html
├── script.js
└── locale
    ├── fr
    └── pt_BR

Translated

app
├── build
│   ├── en
│   │   ├── index.html
│   │   └── script.js  // alert("Hello World");
│   ├── fr
│   │   ├── index.html
│   │   └── script.js  // alert("Bonjour tout le monde");
│   └── pt-br
│       ├── index.html
│       └── script.js  // alert("Olá mundo");
├── index.html
├── script.js
└── locale
    ├── fr
    └── pt_BR

API

options

defaultLang

Type: string|null
Default: 'en'

If a default language is set, an additional language build will be created that uses each msgid as the translated value. Use null to short-circuit this behavior.

localeDirs

Type: Array
Default: ['locale']

Array of [paths to] locale directories. The first directory is used as the canonical list of supported languages. When two directories have catalogs with conflicting translations the directory closer to first is used.

jsonKeys

Type: Array
Default: []

Object keys that require translation. The keys can be nested using a . or a # to indicate an array.

Example, to translate the json:

{
  "flowers": [
    {"name": "roses", "description": "are red"},
    {"name": "violets", "description": "are blue"}
  ],
  "bugs": [
    {"name": "bees", "description": "buzz"}
  ],
  "items": [
    {"item": "title", "value": "some title"},
    {"item": "count", "value": 4},
    {"item": "description", "value": "some description"},
    {"item": "test", "value": true}
  ]
}

Use ['description'] to translate all object descriptions. For just flower descriptions use ['flowers.#.description'].

When translating an array of items, it is sometimes necessary to evaluate a sibling key to determine if the object value requires translation.

Example: to translate all item values that are titles, use: ['items.#.value(item=title)']. To translate items values that are titles or descriptions, use: ['items.#.value(item=title|description)']

Keys using using literal dots, such as:

{
  "properties": {
    "link.text": "Hello World"
  }
}

Can be selected using escaping: properties.link\.text

urlKeys

Type: Array
Default: []

Object keys of urls that require prefixing with language codes. These keys follow the same rules and use the same syntax as jsonKeys, except ignoreKeys will not ignore any urlKeys.

ignoreKeys

Type: Array
Default: null

Object keys that should be ignored. These keys override matching jsonKeys and match anywhere in a nested key. Using example above, if wanting to translate all descriptions except for bugs use options:

{
  jsonKeys: ['description'],
  ignoreKeys: ['bugs']
}

formatSpaces

Type: Int
Default: 0

Number of spaces to use when writing out json.

License

MIT © Yola

Development

Lint and run js tests:

npm test

To run just the js tests:

npm install -g mocha
mocha