eslint-plugin-i18n-messages

ESLint plugin to enforce identical keys across i18n/locale message files. Helps prevent missing translations by ensuring all locale files have the same structure.

Features

• ✅ Validates JSON locale files against a reference file
• ✅ Detects missing keys (in reference but not in current file)
• ✅ Detects extra keys (in current file but not in reference)
• ✅ Supports nested object structures with dot notation
• ✅ Glob pattern support for reference file
• ✅ Bundles JSON parser - no additional dependencies needed
• ✅ Works with both ESLint flat config and legacy config

Installation

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

The plugin bundles jsonc-eslint-parser, so you don't need to install it separately.

Requirements

• Node.js >= 16.0.0
• ESLint >= 8.0.0

Usage

This plugin helps ensure all your locale/translation files have the same keys, preventing missing translations in your application.

Flat Config (eslint.config.js)

import i18nMessages from 'eslint-plugin-i18n-messages';

export default [
  {
    files: ['**/*.json'],
    languageOptions: {
      parser: i18nMessages.parser  // Use the bundled parser
    },
    plugins: {
      'i18n-messages': i18nMessages
    },
    rules: {
      'i18n-messages/identical-keys': ['error', {
        referenceFile: 'locales/en.json'
      }]
    }
  }
];

Or if you prefer to use your own parser installation:

import i18nMessages from 'eslint-plugin-i18n-messages';
import jsoncParser from 'jsonc-eslint-parser';

export default [
  {
    files: ['**/*.json'],
    languageOptions: {
      parser: jsoncParser
    },
    plugins: {
      'i18n-messages': i18nMessages
    },
    rules: {
      'i18n-messages/identical-keys': ['error', {
        referenceFile: 'locales/en.json'
      }]
    }
  }
];

Legacy Config (.eslintrc.js)

module.exports = {
  overrides: [
    {
      files: ['*.json'],
      parser: 'jsonc-eslint-parser',
      plugins: ['i18n-messages'],
      rules: {
        'i18n-messages/identical-keys': ['error', {
          referenceFile: 'locales/en.json'
        }]
      }
    }
  ]
};

Using the Recommended Config (Legacy only)

module.exports = {
  extends: ['plugin:i18n-messages/recommended'],
  rules: {
    'i18n-messages/identical-keys': ['error', {
      referenceFile: 'locales/en.json'  // You still need to specify your reference file
    }]
  }
};

Rule: identical-keys

Ensures all locale files have identical keys to a reference file.

Options

• referenceFile (required): Path to the reference locale file. Supports glob patterns.
• excludeReference (optional, default: true): Whether to exclude the reference file from linting.

Examples

Basic usage

{
  'i18n-messages/identical-keys': ['error', {
    referenceFile: 'src/locales/en.json'
  }]
}

Using glob patterns

{
  'i18n-messages/identical-keys': ['error', {
    referenceFile: 'src/locales/**/en.json'
  }]
}

Include reference file in linting

{
  'i18n-messages/identical-keys': ['error', {
    referenceFile: 'src/locales/en.json',
    excludeReference: false
  }]
}

How it works

The plugin compares the keys in each locale file against the reference file and reports:

• Missing keys: Keys that exist in the reference file but not in the current file
• Extra keys: Keys that exist in the current file but not in the reference file

Example

Given a reference file en.json:

{
  "welcome": "Welcome",
  "goodbye": "Goodbye"
}

And a locale file fr.json:

{
  "welcome": "Bienvenue"
}

ESLint will report:

Missing 1 key from reference file (locales/en.json): "goodbye"

Nested keys

The plugin supports nested object structures:

{
  "auth": {
    "login": "Login",
    "logout": "Logout"
  }
}

Keys are flattened as auth.login and auth.logout for comparison.

Requirements

• Node.js >= 16.0.0
• ESLint >= 8.0.0
• jsonc-eslint-parser >= 2.0.0 (bundled)

Project Structure

src/
├── index.ts              # Main plugin entry point
├── types.ts              # TypeScript type definitions
├── rules/
│   └── identical-keys.ts # Main rule implementation
└── utils/
    ├── ast-helpers.ts         # AST node finding utilities
    ├── find-project-root.ts   # Project root detection
    ├── find-reference-file.ts # Reference file resolution
    ├── get-keys.ts            # Key extraction from objects
    └── index.ts               # Utility exports

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT