@lbello/i18n-diff

A CLI tool to check i18n translation files for missing and extra keys.

Installation

npm install -g @lbello/i18n-diff

Or run directly with npx:

npx @lbello/i18n-diff --folder ./locales

Usage

i18n-diff --folder ./i18n --source en.json

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --folder <path> | -f | Folder containing translation files | ./i18n | | --source <file> | -s | Source language file | en.json | | --format <type> | | JSON structure: flat or nested | flat | | --output <type> | -o | Output format: text, json, or table | text | | --watch | -w | Watch mode: re-run on file changes | false | | --verbose | -v | Show all keys instead of truncating | false | | --strict | | Exit with code 1 for extra keys too | false |

Examples

Basic check:

i18n-diff --folder ./locales --source en.json

Table output:

i18n-diff -f ./locales -o table

JSON output (for CI/CD):

i18n-diff -f ./locales -o json

Watch mode:

i18n-diff -f ./locales -w

Strict mode (fail on extra keys):

i18n-diff -f ./locales --strict

Output Formats

Text (default)

✓ it: OK

✗ de:
  Missing keys (2):
    - farewell
    - buttons.cancel
  Extra keys (1):
    - extra_key

Table

┌──────────┬────────┬─────────┬───────┐
│ Language │ Status │ Missing │ Extra │
├──────────┼────────┼─────────┼───────┤
│ de       │ FAIL   │ 2       │ 1     │
├──────────┼────────┼─────────┼───────┤
│ it       │ OK     │ 0       │ 0     │
└──────────┴────────┴─────────┴───────┘

JSON

{
  "summary": {
    "total": 2,
    "ok": 1,
    "withIssues": 1
  },
  "results": [
    {
      "language": "de",
      "filePath": "/path/to/de.json",
      "status": "fail",
      "missingKeys": ["farewell", "buttons.cancel"],
      "extraKeys": ["extra_key"]
    },
    {
      "language": "it",
      "filePath": "/path/to/it.json",
      "status": "ok",
      "missingKeys": [],
      "extraKeys": []
    }
  ]
}

Supported JSON Formats

Flat

{
  "greeting": "Hello",
  "buttons.submit": "Submit",
  "buttons.cancel": "Cancel"
}

Nested

{
  "greeting": "Hello",
  "buttons": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}

Both formats are automatically flattened for comparison.

Exit Codes

| Code | Description | |------|-------------| | 0 | All translations are complete | | 1 | Missing keys found (or extra keys with --strict) |

Programmatic Usage

import { check, discoverLanguages } from '@lbello/i18n-diff';

const { sourceLang, targetLangs } = await discoverLanguages('./locales', 'en.json');

const results = await check({
  folder: './locales',
  sourceLang,
  targetLangs
});

console.log(results);

License

MIT