i18n-parity

Validate parity of translation keys across locales: reports missing, empty, and extra keys with coverage (%)

Note: Built for next-intl but works with any JSON-based i18n setup.

Feel free to contribute or contact me.

Features

• Missing keys detection
• Empty value detection
• Extra keys detection
• Coverage metrics
• CI/CD
• Fast & lightweight

Install

npm i -D i18n-parity

bun add -d i18n-parity

Usage

i18n-parity --ref en --dir ./src/locales

Options

Flag	Description	Default
--ref	Reference locale (filename w/o .json)	fr
--dir	Directory with locale JSON files	./src/locales
--format	table or json	table
--fail-on	Exit with error on: missing, empty, extra	none

Examples

# Basic usage
i18n-parity --ref en --dir ./locales

# JSON output for CI
i18n-parity --format json

# Fail on missing or empty translations
i18n-parity --fail-on missing,empty

Output looks like this:

┌─────────┬──────────┬─────────┬───────┬───────┐
│ locale  │ coverage │ missing │ empty │ extra │
├─────────┼──────────┼─────────┼───────┼───────┤
│ es      │ 85.71%   │ 1       │ 1     │ 1     │
│ de      │ 100%     │ 0       │ 0     │ 0     │
└─────────┴──────────┴─────────┴───────┴───────┘

[es] Missing keys (1):
  - navigation.compass
[es] Empty keys (1):
  - commands.anchor

API

import { checkI18n, diff } from "i18n-parity";

const results = await checkI18n("en", "src/locales");
console.log(results[0].coveragePercent);

The DiffResult type:

type DiffResult = {
  locale: string;
  totalLeafKeys: number;
  presentLeafKeys: number;
  coveragePercent: number;
  missingKeys: string[];
  emptyKeys: string[];
  extraKeys: string[];
}

CI Setup

GitHub Actions:

- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun i18n-parity --ref en --dir ./locales --fail-on missing,empty

License

MIT