eslint-plugin-i18n-json

4.0.1 verified Sat Apr 25 auth: no javascript

An ESLint plugin for linting JSON i18n translation files, version 4.0.1. It validates JSON syntax, ICU message syntax, checks identical keys across locales, sorts keys, and ensures placeholder consistency. Requires ESLint >=4.0.0. Maintained by GoDaddy with a focus on fully extendable rules and settings (e.g., custom message syntax, custom sort, key ignoring). Supports flat config (ESLint >=9) and nested keys. Release cadence is intermittent; last update April 2024 fixing Lodash deprecation.

Common errors

error Error: ESLint configuration in .eslintrc is invalid: - Unexpected top-level property "i18n-json/ignore-keys" ↓

cause Settings for i18n-json/ignore-keys must be placed under the 'settings' key, not at the top level of .eslintrc.

fix

Move "i18n-json/ignore-keys": [...] inside the "settings" object: { "settings": { "i18n-json/ignore-keys": [...] } }.

error Error: Cannot find module '@formatjs/icu-messageformat-parser' ↓

cause The plugin requires @formatjs/icu-messageformat-parser for the default valid-message-syntax rule; it is not installed automatically.

fix

Run npm install --save-dev @formatjs/icu-messageformat-parser or disable the rule if not needed.

error Error: Failed to load plugin 'i18n-json': Cannot find module 'eslint-plugin-i18n-json' ↓

cause The plugin is not installed or ESLint cannot resolve it; common in monorepos without hoisting.

fix

Ensure eslint-plugin-i18n-json is listed in devDependencies and installed. If using workspaces, ensure the package is in the root node_modules.

Warnings

gotcha The identical-keys rule requires a reference locale file path specified via 'filePath' option; without it, the rule will not work and may produce confusing errors. ↓

fix Add the 'filePath' option to the rule configuration pointing to your source locale file (e.g., './translations/en-US/index.json').

gotcha The default sort for sorted-keys is case-sensitive ascending. If your project uses case-insensitive or natural sort, you must provide a custom sort function. ↓

fix Configure a custom sort function in rule options: `"i18n-json/sorted-keys": ["error", { "sortFunction": "natural" }]` or a custom comparator.

deprecated Lodash per-function packages (like lodash.get, lodash.set) were deprecated and removed; internal usage migrated to main lodash in v4.0.1. ↓

fix Update to v4.0.1 or above to avoid deprecated modules.

gotcha The plugin does not lint files outside of the ESLint file glob; you must include your translation files in ESLint's 'overrides' or include patterns (e.g., 'translations/**/*.json'). ↓

fix Add an overrides block in .eslintrc: `"overrides": [{ "files": ["translations/**/*.json"], "rules": { ... } }]`.

breaking Flat config (ESLint >=9) changes how plugins are loaded; CJS require() will not work; must use ESM import. ↓

fix Use `import i18nJson from 'eslint-plugin-i18n-json'` and attach as object property in flat config array.

Install

npm install eslint-plugin-i18n-json

yarn add eslint-plugin-i18n-json

pnpm add eslint-plugin-i18n-json

Imports

plugin (eslint config)

wrong

const plugin = require('eslint-plugin-i18n-json'); // Direct require is not typical; use config file plugins field

correct

// In .eslintrc plugins array
"plugins": ["i18n-json"]

Plugin is loaded via ESLint config, not directly imported in code.

recommended config

wrong

extends: ["eslint-plugin-i18n-json"]

correct

// .eslintrc
extends: ["plugin:i18n-json/recommended"]

Use the plugin prefix 'plugin:' for accessing rulesets.

individual rule
wrong
```
"valid-json": "error"
```
correct
```
// .eslintrc rules
"i18n-json/valid-json": "error"
```
All rules must be namespaced with 'i18n-json/' prefix.

flat config (ESLint >=9)

wrong

const i18nJson = require('eslint-plugin-i18n-json'); // CJS not supported in flat config; use import

correct

import i18nJson from 'eslint-plugin-i18n-json';
export default [
  { plugins: { 'i18n-json': i18nJson }, rules: { 'i18n-json/valid-json': 'error' } }
];

Flat config requires ESM import of the plugin object.

Quickstart

Install the plugin and ESLint, configure .eslintrc.json with recommended rules and identical-keys, create sample translation files, and run ESLint.

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

# Create .eslintrc.json in project root
cat > .eslintrc.json << 'EOF'
{
  "plugins": ["i18n-json"],
  "extends": ["plugin:i18n-json/recommended"],
  "rules": {
    "i18n-json/identical-keys": ["error", { "filePath": "./translations/en-US/index.json" }],
    "i18n-json/identical-placeholders": "error"
  },
  "settings": {
    "i18n-json/ignore-keys": ["_metadata"]
  }
}
EOF

# Create sample translation files
mkdir -p translations/en-US translations/es-MX
echo '{"greeting": "Hello", "farewell": "Goodbye"}' > translations/en-US/index.json
echo '{"greeting": "Hola", "farewell": "Adiós"}' > translations/es-MX/index.json

# Run ESLint on the translation directory
npx eslint translations/