eslint-plugin-i18n-json
Advanced tools
Fully extendable eslint plugin for JSON i18n translation files.
Fully extendable eslint plugin for JSON i18n translation files.
🎉 Check out the introductory blog post!
< 9.0.0)>= 9.0.0lint JSON translation files
i18n-json/valid-jsonvalidate syntax per message
i18n-json/valid-message-syntaxensure translation files have identical keys
i18n-json/identical-keyssort translation keys in ascending order through eslint auto-fix (case-sensitive)
i18n-json/sorted-keysensure translation files have identical placeholders
i18n-json/identical-placeholdersability to ignore certain keys. Example: metadata keys, in progress translations, etc.
i18n-json/ignore-keys ExampleThe 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.
Check out the Examples folder to see different use cases.
Right out of the box you get the following through our recommended ruleset i18n-json/recommended:
@formatjs/icu-messageformat-parser)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
If you are using eslint < 9.0.0 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.
--fix option, sorting the translation file won't workstylish, 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/"
}
}
compact, unix, visualstudio, json. Learn more here
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.
< 9.0.0)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:
.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,
},
};
>= 9.0.0>= 9.0.0 uses flat configuration// eslint.config.(m)js
import i18nJsonPlugin from 'eslint-plugin-i18n-json';
export default {
files: ['**/*.json'],
plugins: { 'i18n-json': i18nJsonPlugin },
processor: {
meta: { name: '.json' },
...i18nJsonPlugin.processors['.json'],
},
rules: {
...i18nJsonPlugin.configs.recommended.rules,
'i18n-json/valid-message-syntax': 'off',
},
};
linting of each JSON translation file
builtin linter uses json-lint
default severity: error | 2
options
linter: String (Optional)
Function(source: String)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.
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)message and its corresponding keyJSON.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.
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'),
},
}],
},
};
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.
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.
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).
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.
.eslintrc.* file.filePath : String (Required)
// .eslintrc.js
module.exports = {
rules: {
'i18n-json/identical-placeholders': [2, {
filePath: path.resolve('path/to/locale/en-US.json'),
}],
},
};
i18n-json/identical-keys, i18n-json/valid-syntax and i18n-json/identical-placeholders.a was added to the ignore-keys list, then a.b will also be ignored.
{
"a": {
"b": "translation"
}
}
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'
],
},
}
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.
MIT
[4.0.1]
>= 9.0.0 as described in https://github.com/godaddy/eslint-plugin-i18n-json/issues/62FAQs
Fully extendable eslint plugin for JSON i18n translation files.
The npm package eslint-plugin-i18n-json receives a total of 72,441 weekly downloads. As such, eslint-plugin-i18n-json popularity was classified as popular.
We found that eslint-plugin-i18n-json demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 14 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.