i18next Parser
When translating an application, maintaining the translation catalog by hand is painful. This package parses your code and automates this process.
Finally, if you want to make this process even less painful, I invite you to check Locize. They are a sponsor of this project. Actually, if you use this package and like it, supporting me on Patreon would mean a great deal!
Features
- Choose your weapon: A CLI, a standalone parser or a stream transform
- 6 built in lexers: Javascript, JSX, HTML, Handlebars, TypeScript+tsx and Vue
- Creates one catalog file per locale and per namespace
- Backs up the old keys your code doesn't use anymore in
namespace_old.json
catalog - Restores keys from the
_old
file if the one in the translation file is empty - Parses comments for static keys to support dynamic key translations.
- Supports i18next features:
- Context: keys of the form
key_context
- Plural: keys of the form
key_zero
, key_one
, key_two
, key_few
, key_many
and key_other
as described here
- Tested on Node 10+. If you need support for 6 and 8, look at the
1.0.x
versions.
Versions
You can find information about major releases on the dedicated page. The migration documentation will help you figure out the breaking changes between versions.
For legacy users on 0.x
, the code has since been entirely rewritten and there is a dedicated branch for it. You are highly encouraged to upgrade!
Usage
CLI
You can use the CLI with the package installed locally but if you want to use it from anywhere, you better install it globally:
yarn global add i18next-parser
npm install -g i18next-parser
i18next 'app/**/*.{js,hbs}' 'lib/**/*.{js,hbs}' [-oc]
Multiple globbing patterns are supported to specify complex file selections. You can learn how to write globs here. Note that glob must be wrapped with single quotes when passed as arguments.
IMPORTANT NOTE: If you pass the globs as CLI argument, they must be relative to where you run the command (aka relative to process.cwd()
). If you pass the globs via the input
option of the config file, they must be relative to the config file.
- -c, --config : Path to the config file (default: i18next-parser.config.js).
- -o, --output : Path to the output directory (default: locales/$LOCALE/$NAMESPACE.json).
- -s, --silent: Disable logging to stdout.
- --fail-on-warnings: Exit with an exit code of 1 on warnings
- --fail-on-update: Exit with an exit code of 1 when translations are updated (for CI purpose)
Gulp
Save the package to your devDependencies:
yarn add -D i18next-parser
npm install --save-dev i18next-parser
Gulp defines itself as the streaming build system. Put simply, it is like Grunt, but performant and elegant.
const i18nextParser = require('i18next-parser').gulp;
gulp.task('i18next', function() {
gulp.src('app/**')
.pipe(new i18nextParser({
locales: ['en', 'de'],
output: 'locales/$LOCALE/$NAMESPACE.json'
}))
.pipe(gulp.dest('./'));
});
IMPORTANT: output
is required to know where to read the catalog from. You might think that gulp.dest()
is enough though it does not inform the transform where to read the existing catalog from.
Broccoli
Save the package to your devDependencies:
yarn add -D i18next-parser
npm install --save-dev i18next-parser
Broccoli.js defines itself as a fast, reliable asset pipeline, supporting constant-time rebuilds and compact build definitions.
const Funnel = require('broccoli-funnel')
const i18nextParser = require('i18next-parser').broccoli
const appRoot = 'broccoli'
let i18n = new Funnel(appRoot, {
files: ['handlebars.hbs', 'javascript.js'],
annotation: 'i18next-parser'
})
i18n = new i18nextParser([i18n], {
output: 'broccoli/locales/$LOCALE/$NAMESPACE.json'
})
module.exports = i18n
Options
Using a config file gives you fine-grained control over how i18next-parser treats your files. Here's an example config showing all config options with their defaults.
module.exports = {
contextSeparator: '_',
createOldCatalogs: true,
defaultNamespace: 'translation',
defaultValue: '',
indentation: 2,
keepRemoved: false,
keySeparator: '.',
lexers: {
hbs: ['HandlebarsLexer'],
handlebars: ['HandlebarsLexer'],
htm: ['HTMLLexer'],
html: ['HTMLLexer'],
mjs: ['JavascriptLexer'],
js: ['JavascriptLexer'],
ts: ['JavascriptLexer'],
jsx: ['JsxLexer'],
tsx: ['JsxLexer'],
default: ['JavascriptLexer']
},
lineEnding: 'auto',
locales: ['en', 'fr'],
namespaceSeparator: ':',
output: 'locales/$LOCALE/$NAMESPACE.json',
pluralSeparator: '_',
input: undefined,
sort: false,
skipDefaultValues: false,
useKeysAsDefaultValue: false,
verbose: false,
failOnWarnings: false,
failOnUpdate: false,
customValueTemplate: null,
resetDefaultValueLocale: null
}
Lexers
The lexers
option let you configure which Lexer to use for which extension. Here is the default:
Note the presence of a default
which will catch any extension that is not listed.
There are 4 lexers available: HandlebarsLexer
, HTMLLexer
, JavascriptLexer
and
JsxLexer
. Each has configurations of its own. Typescript is supported via JavascriptLexer
and JsxLexer
.
If you need to change the defaults, you can do it like so:
Javascript
The Javascript lexer uses Typescript compiler to walk through your code and extract translation functions.
The default configuration is below:
{
js: [{
lexer: 'JavascriptLexer',
functions: ['t'],
}],
}
Jsx
The JSX lexer builds off of the Javascript lexer and extends it with support for JSX syntax.
Default configuration:
{
jsx: [{
lexer: 'JsxLexer',
attr: 'i18nKey',
}],
}
If your JSX files have .js
extension (e.g. create-react-app projects) you should override the default js
lexer with JsxLexer
to enable jsx parsing from js files:
{
js: [{
lexer: 'JsxLexer'
}],
}
Ts(x)
Typescript is supported via Javascript and Jsx lexers. If you are using Javascript syntax (e.g. with React), follow the steps in Jsx section, otherwise Javascript section.
Handlebars
{
handlebars: [
{
lexer: 'HandlebarsLexer',
functions: ['t']
}
]
}
Html
{
html: [{
lexer: 'HtmlLexer',
attr: 'data-i18n'
optionAttr: 'data-i18n-options'
}]
}
Custom lexers
You can provide function instead of string as a custom lexer.
const CustomJsLexer = require('./CustomJsLexer');
{
js: [CustomJsLexer],
jsx: [{
lexer: CustomJsLexer,
customOption: true
}]
}
Caveats
While i18next extracts translation keys in runtime, i18next-parser doesn't run the code, so it can't interpolate values in these expressions:
t(key)
t('key' + id)
t(`key${id}`)
As a workaround you should specify possible static values in comments anywhere in your file:
// t('key_1')
// t('key_2')
t(key)
/*
t('key1')
t('key2')
*/
t('key' + id)
Events
The transform emits a reading
event for each file it parses:
.pipe( i18next().on('reading', (file) => {}) )
The transform emits a error:json
event if the JSON.parse on json files fail:
.pipe( i18next().on('error:json', (path, error) => {}) )
The transform emits a warning
event if the file has a key that is not a string litteral or an option object with a spread operator:
.pipe( i18next().on('warning', (path, key) => {}) )
Here is a list of the warnings:
- Key is not a string literal: the parser cannot parse variables, only literals. If your code contains something like
t(variable)
, the parser will throw a warning. - Found same keys with different values: if you use different default values for the same key, you'll get this error. For example, having
t('key', {defaultValue: 'foo'})
and t('key', {defaultValue: bar'})
. The parser will select the latest one. - Found translation key already mapped to a map or parent of new key already mapped to a string: happens in this kind of situation:
t('parent', {defaultValue: 'foo'})
and t('parent.child', {defaultValue: 'bar'})
. parent
is both a translation and an object for child
.
Contribute
Any contribution is welcome. Please read the guidelines first.
Thanks a lot to all the previous contributors.
If you use this package and like it, supporting me on Patreon is another great way to contribute!