i18n-compile
NodeJS module for assembling JSON translation files from language-merged YAML input files.
Output files are compatible with angular-translate and i18next
Getting Started
Installation:
npm install i18n-compile --save-dev
Usage as a CLI executable:
Usage: i18n-compile [options] <files...> Options: -h, --help output usage information -o, --out <dest> Output file path. May contain language placement token -m, --merge Whether to merge all languages into a single file -l, --lang-place [token] Placeholder
Usage as a node module:
var i18nCompile = ; ; // or from a string var yamlString = ... // yaml as a string var translations = i18nCompile;// translations => {lang1: {...}, lang2: {...}, ...}
The translation format
The format is inspired by grunt-translate-compile.
It is intended to greatly reduce the amount of typing needed to translate your app.
The YAML file format is used because it requires less typing compared to JSON - no need to enclose both properties and values in " "
s,
and nesting is done by indentation instead of blocks of curly braces.
The structure of the translations inside the file is like the following:
MENU: CART: EMPTY: en: Empty Cart pt: Esvaziar Carrinho es: Vaciar Carrito CHECKOUT: en: Checkout pt: Fechar Pedido es: Realizar Pedido USER: LABEL: en: User pt: Usuário es: Usuario DROPDOWN: EDIT: en: Edit pt: Editar es: Editar LOGOUT: en: Logout pt: Sair es: Finalizar la Sesión
Notice how the translation values are assigned directly to the language keys. This way translations for all languages can be described in a single file, which eliminates the need to copy the translation ids over to other files for each language that you have.
That structure reduces the size of your sources and makes your translations more manageable.
Compiling the above example will result in the following output files:
-
translation_en.json
-
translation_pt.json
-
translation_es.json
Using the module
Arguments
var i18nCompile = require('i18n-compile');
i18nCompile(<file-patterns>, <destination>, [<options>]);
-
#### File patterns Type:
Array
ofString
sA list of file names or glob patterns. Those are the input files to be compiled.
-
#### Destination Type:
String
Destination path for the compile output.
-
#### Options Type:
Object
#### options.langPlace Type:
String
Default value:''
(empty string)If specified, and if present in the destination path, the value will be replaced with the language id. For example:
i18n_compile(..., 'output/path/file-[lang]-i18n.json', {langPlace: '[lang]'}); results in output files(for languages 'en', 'bg', 'pt): 'output/path/file-en-i18n.json' 'output/path/file-bg-i18n.json' 'output/path/file-pt-i18n.json'
This option only has effect when the
merge
option isfalse
.#### options.merge Type:
Boolean
Default value:false
If
true
the output will be a single file with the translations for all languages merged inside it.
Usage Examples
Default Options
In this example, the compiled translations for each language are written to a separate file
;
The language id is by default inserted right before the last .
of the file name.
So if we have the languages en
and bg
, the resulting files will be:
dest/translations-en.json
dest/translations-bg.json
If there is no .
present then the language id is inserted at the end of the file name:
;
dest/translations-en
dest/translations-bg
Placement of language id
In this example, the language id is placed at a custom location in the output file path
;
So if we have the languages en
and bg
, the resulting files will be
dest/path/en-translations.json
dest/path/bg-translations.json
Merge translations in one file
With merge
set to true
the compiled translations for all languages are merged into a single file
;
fromString
method
Using the Arguments
var i18nCompile = require('i18n-compile');
var translations = i18nCompile.fromString(<input>, [<filename>]);
-
#### input Type:
String
yaml
content as string. -
#### filename Type:
String
File path to use when displaying errors.
Return value
A javascript object mapping each language name to the translations object for that language.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.