@rafaelgomesxyz/eslint-plugin-i18n-json

v4.1.0

Published

3 years ago

Fully extendable eslint plugin for JSON i18n translation files.

Downloads

0High
0Medium
0Low

rafaelgomesxyz

eslint json i18n translations internationalization intl linter

eslint-plugin-i18n-json

Fully extendable eslint plugin for JSON i18n translation files.

🎉 Check out the introductory blog post!

Features 🚀

lint JSON translation files
- rule: i18n-json/valid-json
- configure a custom linter in case the default doesn't fit your needs.
validate syntax per message
- rule: i18n-json/valid-message-syntax
- default syntax check is for ICU Message Syntax
- can support any message syntax through custom validators. Example
ensure translation files have identical keys
- rule: i18n-json/identical-keys
- supports different custom mappings and on the fly key structure generation
sort translation keys in ascending order through eslint auto-fix (case-sensitive)
- rule: i18n-json/sorted-keys
- can support a custom sort function to satisfy different sorting needs
ability to ignore certain keys. Example: metadata keys, in progress translations, etc.
- setting: i18n-json/ignore-keys Example
The plugin supports any level of nesting in the translation file. (escapes . in key names)

Note: Check out the Examples folder to see different use cases and project setups.

Requires

eslint >= 4.0.0
node >= 8.6.0

Examples

Check out the Examples folder to see different use cases.

Getting Started

Right out of the box you get the following through our recommended ruleset i18n-json/recommended:

i18n-json/valid-json
- linting of each JSON translation file
- default severity: error | 2
i18n-json/valid-message-syntax
- default ICU Message syntax validation (using @formatjs/icu-messageformat-parser)
- default severity: error | 2
i18n-json/sorted-keys
- automatic case-sensitive ascending sort of all keys in the translation file.
- Does a level order traversal of keys, and supports sorting nested objects

Let's say your translations project directory looks like the following, (project name: simple)

> tree simple -I node_modules

simple
├── package.json
├── readme.md
└── translations
    ├── en-US
    │   └── index.json
    └── es-MX
        └── index.json

In this project directory, do the following:

npm install --save-dev eslint-plugin-i18n-json
Create a .eslintrc.js file in the root dir of your project. For this example: /simple/.eslintrc.js.

paste in the following:

module.exports = {
  extends: [
    'plugin:i18n-json/recommended',
  ],
};

add this npm script to your package.json file.
- note:
  - without the --fix option, sorting the translation file won't work
  - the default eslint report formatter, stylish, doesn't handle lint messages of varying length well. Hence, we have also built a custom report formatter well suited for this plugin.
```
{
  "scripts": {
    "lint": "eslint --fix --ext .json --format node_modules/eslint-plugin-i18n-json/formatter.js translations/"
  }
}
```
- Also, the following builtin formatters provided by eslint also work well: compact, unix, visualstudio, json. Learn more here
  - Example usage: eslint --fix --ext .json --format compact translations/
npm run lint
Profit! Relax knowing that each change to the translations project will go through strict checks by the eslint plugin.
Example where we have invalid ICU message syntax.

Configuring your .eslintrc file

Simply update your .eslintrc.* with overrides for the individual rules.
Eslint severities: 2 = error, 1 = warning, 0 = off

Example of the module's default rule configuration:

see below for more information about how to further configure each rule. (some options may require switching to a .eslintrc.js file)

// .eslintrc.json
{
  "rules": {
      "i18n-json/valid-message-syntax": [2, {
        "syntax": "icu"
      }],
      "i18n-json/valid-json": 2,
      "i18n-json/sorted-keys": [2, {
        "order": "asc",
        "indentSpaces": 2,
      }],
      "i18n-json/identical-keys": 0
  }
}

// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/valid-message-syntax': [2, {
      syntax: 'icu',
    }],
    'i18n-json/valid-json': 2,
    'i18n-json/sorted-keys': [2, {
      order: 'asc',
      indentSpaces: 2,
    }],
    'i18n-json/identical-keys': 0,
  },
};

Rules

i18n-json/valid-json

linting of each JSON translation file
builtin linter uses json-lint
default severity: error | 2

options

linter: String (Optional)

Absolute path to a module which exports a JSON linting function.

Function(source: String)
This function will be passed the source of the current file being processed.

It should throw an Error, just like JSON.parse.

// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/valid-json': [2, {
      linter: path.resolve('path/to/custom-linter.js'),
    }],
  },
};

// custom-linter.js
module.exports = (source) => {
  if (isBad(source)) {
    throw new SyntaxError('invalid syntax');
  }
};

Example output for Invalid JSON.

i18n-json/valid-message-syntax

default ICU Message syntax validation (using @formatjs/icu-messageformat-parser)
default severity: error | 2

options

syntax: String (Optional). Default value: icu.

Can be a built in validator: icu, non-empty-string.

// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/valid-message-syntax': [2, {
      syntax: 'non-empty-string',
    }],
  },
};

Can be an absolute path to a module which exports a Syntax Validator Function.

Function(message: String, key: String)
This function will be invoked with each message and its corresponding key

It should throw an Error, just like JSON.parse on invalid syntax.

// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/valid-message-syntax': [2, {
      syntax: path.resolve('path/to/custom-syntax-validator.js'),
    }],
  },
};

// custom-syntax-validator.js example
module.exports = (message, key) => {
  // each message should be in all caps.
  if (message !== message.toUpperCase()) {
    throw new SyntaxError('MESSAGE MUST BE IN ALL CAPS!');
  }
};

Output from the custom-message-syntax example where each message must have the word 'PIZZA' prepended to it.

i18n-json/identical-keys

compare each translation file's key structure with a reference translation file to ensure consistency
severity: 0 | off , this rule is OFF by default
Can turn this rule on by specifying options for it through your .eslintrc.* file.
options
- filePath : String | Object (Required)
  - Can be an absolute path to the reference translation file.
```
// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/identical-keys': [2, {
      filePath: path.resolve('path/to/locale/en-US.json'),
    }],
  },
};
```
  - Can be an Object which contains a Mapping for how to choose a reference translation file. (chosen by suffix match)
```
// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/identical-keys': [2, {
      filePath: {
        'login.json': path.resolve('./translations/en-US/login.json'),
        'search-results.json': path.resolve('./translations/en-US/search-results.json'),
        'todos.json': path.resolve('./translations/en-US/todos.json'),
      },
    }],
  },
};
```
    - values in the path must be the absolute file path to the reference translation file.
    - the plugin will do a suffix match on the current file's path to determine which reference translation file to choose.
  - Can be an absolute path to an exported function which generates the reference key structure on the fly. The function will be passed the parsed JSON translations object and absolute path of the current file being processed.
    - Function(translations: Object, currentFileAbsolutePath: String) : Object
```
// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/identical-keys': [2, {
      filePath: path.resolve('path/to/key-structure-generator.js'),
    }],
  },
};
```
```
// key-structure-generator.js example
module.exports = (translations, currentFileAbsolutePath) => {
  // identity key structure generator
  return translations;
};
```
- checkDuplicateValues: Boolean (Optional). Default value: false. If true, the values will also be checked for duplicates, in comparison to the file specified in filePath.
Output from the slightly advanced identical keys example where some keys from the reference translation file (en-US) were not found during comparison.

i18n-json/sorted-keys

automatic case-sensitive ascending sort of all keys in the translation file
if turned on, the this rule by will sort keys in an ascending order by default.
default severity: error | 2
options
- sortFunctionPath: String (Optional). Absolute path to a module which exports a custom sort function. The function should return the desired order of translation keys. The rule will do a level order traversal of the translations and call this custom sort at each level of the object, hence supporting nested objects. This option takes precedence over the order option.
  - NOTE: eslint does additional verification passes on your files after a "fix" is applied (in our case, once the sorted keys are written back to your JSON file). Ensure your sort function won't switch the ordering once the keys are already sorted. For example, if your sort function looks like Object.keys(translations).reverse(), then on the initial pass your keys would be sorted correctly, but in the next pass the order of keys would again be reversed. This would lead to a loop where eslint cannot verify the fix is working correctly. Eslint will not apply the intended sorting fixes in this scenarios.
  - Function(translations: Object) : Array
```
// .eslintrc.js
module.exports = {
  rules: {
    'i18n-json/sorted-keys': [2, {
      sortFunctionPath: path.resolve('path/to/custom-sort.js'),
    }],
  },
};
```
```
// custom-sort.js example
// Ascending sort
module.exports = (translations) => {
  return Object.keys(translations).sort((keyA, keyB) => {
    if (keyA == keyB) {
      return 0;
    } else if (keyA < keyB) {
      return -1;
    } else {
      return 1;
    }
  })
};
```
- order: String (Optional). Possible values: asc|desc. Default value: asc. Case-sensitive sort order of translation keys. The rule does a level order traversal of object keys. Supports nested objects. Note: if you supply a custom sort function through sortFunctionPath, then this option will be ignored.
- indentSpaces : Number (Optional). Default value: 2. The number of spaces to indent the emitted sorted translations with. (Will be passed to JSON.stringify when generating fixed output).
- useTabs: Boolean (Optional). Default value: false. Use tabs instead of spaces to indent the emitted sorted translations. (Will be passed to JSON.stringify when generating fixed output). If useTabs and indentSpaces are both provided, indentSpaces is ignored. In the case --fix is not supplied to eslint, and the i18n-json/sorted-keys rule is not switched off, it will emit an error (or warning) if it detects an invalid sort order for translation keys.

Settings

i18n-json/ignore-keys

list of key paths (case sensitive) to ignore when checking syntax and doing key structure comparisons. Example
you can also use glob patterns (this package uses micromatch)
- e.g. if the pattern *.inProgress was added to the ignore-keys list, then all of the inProgresskeys below will be ignored.
```
{
  "a": {
    "inProgress": "translation"
  },
  "b": {
    "inProgress": "translation"
  },
  "c": {
    "inProgress": "translation"
  }
}
```
this setting is used by the following rules: i18n-json/identical-keys and i18n-json/valid-syntax
if the key path points to an object, the nested paths are also ignored.
- e.g. if the key a was added to the ignore-keys list, then a.b will also be ignored.
```
{
  "a": {
    "b": "translation"
  }
}
```
example usage: metadata keys with values not corresponding to the syntax specified or work-in-progress translation keys which should not be used in comparisons.

Example setting configuration:

// .eslintrc.js
{
  settings: {
    /*
      None of the key paths listed below
      will be checked for valid i18n syntax
      nor be used in the identical-keys rule comparison.
      (if the key path points to an object, the nested paths are also ignored)
    */
    'i18n-json/ignore-keys': [
      'translationMetadata',
      'login.form.inProgressTranslationKey',
      'some-key'
    ],
  },
}

Disclaimer

None of the translations in the examples provided reflect actual GoDaddy translations. They were just created using Google Translate for example's sake 😉.

Special Thanks 👏

Jest platform packages
@formatjs/icu-messageformat-parser
report formatter ui heavily inspired from: https://github.com/sindresorhus/eslint-formatter-pretty
"Translate" icon created by Björn Andersson, from the Noun Project. Used with attribution under Creative Commons.

License 📋

MIT