eslint-plugin-i18n-json

eslint-plugin-i18n-json

Fully extendable eslint plugin for JSON i18n translation files.

🎉 Check out the introductory blog post!

Table of Contents

• Features
• Getting started
• Examples
• Configuring your .eslintrc file
• Rules
  • i18n-json/valid-json
  • i18n-json/valid-message-syntax
  • i18n-json/identical-keys
  • i18n-json/sorted-keys
• Settings
  • i18n-json/ignore-keys
• Special Thanks
• License
• Changelog

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

• 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 >= 6.0.0

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 intl-messageformat-parser)
  • default severity: error | 2
• i18n-json/sorted-keys
  • automatic case-sensitive ascending sort of all keys in the translation file.
  • configurable to sort in descending order
  • 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:

1. npm install --save-dev eslint-plugin-i18n-json

2. Create a .eslintrc.js file in the root dir of your project. For this example: /simple/.eslintrc.js.

3. paste in the following:

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

4. 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/

5. npm run lint

6. Profit! Relax knowing that each change to the translations project will go through strict checks by eslint plugin.

   Example where we have invalid ICU message syntax.

   

Examples

Check out the Examples folder to see different use cases.

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 intl-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;
      };
      

  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

• default severity: error | 2

• options

  • 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.
  • 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).

  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
• 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

• intl-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

Changelog

[2.4.0] - 2018-07-01

Added

• New plugin setting: i18n-json/ignore-keys. Takes a list of key paths (case sensitive) to ignore when checking syntax and doing key structure comparisons. Only acknowledged by the identical-keys and valid-syntax rules. See README for more details on use.
• new example project for i18n-json/ignore-keys to showcase usage.
• Related PRs
  • #17