i18next-json-sync

i18next-json-sync

Keeps i18next JSON resource files in sync against a primary language, including plural forms. When hooked up to a build process/CI server, ensures keys added/removed from one language are correctly propagated to the other languages, reducing the chance for missing or obselete keys, merge conflicts, and typos.

Example

Given these files:

 locales
 ├── en.json
 ├── fr.json
 └── ru.json

en.json
{
  "key_one": "value",
  "book": "book",
  "book_plural": "books"
}

fr.json
{
  "key_one": "french value"
}

ru.json
{
  "extra_key": "extra value"
}

fr.json and ru.json can be synced against en.json:

import sync from 'i18next-json-sync'
sync({
  files: 'locales/*.json',
  primary: 'en'
});

resulting in:

en.json
{
  "key_one": "value",
  "book": "book",
  "book_plural": "books"
}

fr.json
{
  "key_one": "french value",
  "book": "book",
  "book_plural": "books"
}

ru.json
{
  "key_one": "value",
  "book_0": "books",
  "book_1": "books",
  "book_2": "books"
}

key_one was left alone in fr.json since it's already localized, but book and book_plural were copied over. An extraneous key in ru.json was deleted and keys from en.json copied over. Plurals are mapped between languages according to the i18next suffix rules.

Note: Languages with only one suffix shared for singular and plural forms will not provide plural mappings if they are used as the primary language.

This works on one folder at a time, but can deal with whatever the files glob returns. Files are grouped into directories before processing starts. Folders without a 'primary' found are ignored.

Usage

$ npm install i18next-json-sync --save-dev

In node.js

import sync from 'i18next-json-sync';
//or in ES5 world:
//const sync = require('i18next-json-sync').default;

//defaults are inline:
sync({
  /** Audit files in memory instead of changing them on the filesystem and
    * throw an error if any changes would be made */
  check: false,
  /** Glob pattern for the resource JSON files */
  files: '**/locales/*.json',
  /** An array of glob patterns to exclude from the files search */
  excludeFiles: ['**/node_modules/**'],
  /** Primary localization language. Other language files will be changed to match */
  primary: 'en',
  /** Language files to create if they don't exist, e.g. ['es, 'pt-BR', 'fr'] */
  createResources: [],
  /** Space value used for JSON.stringify when writing JSON files to disk */
  space: 4,
  /** Line endings used when writing JSON files to disk. Either LF or CRLF */
  lineEndings: 'LF',
  /** Insert a final newline when writing JSON files to disk */
  finalNewline: false,
  /** Use empty string for new keys instead of the primary language value */
  newKeysEmpty: false
})

CLI

It can be installed globally and run with sync-i18n, but package.json scripts are a better fit.

{
  "name": "my-app",
  "scripts": {
    "i18n": "sync-i18n --files '**/locales/*.json' --primary en --languages es fr ja zh ko --space 2",
    "check-i18n": "npm run i18n -- --check"
  }
}

Then use npm run i18n to sync on the filesystem and npm run check-i18n to validate.

All options are available via CLI. Use -h or --help to get help output.

License

MIT