chki18n for JavaScript

chki18n.cdget.com

The documentation site has every check, every option and every example. This README is the quick start.

chki18n checks that your i18n translation files agree with each other. Point it at a folder of JSON, name the language everything is compared against, and it reports what is missing, what was never translated and what broke without anyone noticing.

• Twenty-five checks — missing keys, empty values, strings nobody translated, mismatched interpolation placeholders, drifting terminology, and, pointed at your sources, keys nothing references and keys nothing defines. The full list is on the documentation site.
• Every layout — one file per locale, one folder per locale, or one file holding them all.
• CLI and library share one set of checks and one set of options.
• A report in the shape you need — grouped by language, check, file or nothing; rendered for a terminal, for grep, as JSON, as Markdown or as GitHub Actions annotations; saved to a file on request.
• ESM and typed, with two small runtime dependencies, both for the command line. An in-memory comparison of 5,000 keys across 5 locales takes about 17ms.

Install

npm install chki18n

Requires Node.js 22 or newer.

From the command line

npx chki18n ./locales --target en

  Path     ./locales
  Target   en
  Locales  en, ko
  Layout   single, 1 group, 10 keys

 ko ──────────────────────────────────────────────────────────────────────── 1 error · 1 warning

  ERROR  NO_KEY (1)
         The key exists in the target language but is missing here.
    attr.folder  en: "Folder"

  WARN   NOT_TRANSLATED_VALUE (1)
         The value is identical to the target language, so the translation may be incomplete.
    desc.no-str  en: "12345"

 Summary ───────────────────────────────────────────────────────────────────────────────────────

  Compared 10 keys across 2 locales in 1 group. (3ms)
  1 error · 1 warning
  Clean: en

  FAIL  1 error must be fixed before this passes.

Exits with 1 when an error level issue was found, so a CI job fails on it. npx chki18n --help lists every flag.

--group-by decides what a section is (locale, code, group, file or none), --reporter decides the shape (pretty, list, json, markdown or github), and --output keeps a copy:

npx chki18n ./locales --target en --reporter json > report.json
npx chki18n ./locales --target en --output translation-report.md

From JavaScript

Four entry points, depending on who owns the translations:

import {
	analyzeTranslations,
	checkTranslationFiles,
	createAnalyzer,
	loadTranslations
} from 'chki18n';

// Check a directory once — the same thing the CLI does.
const result = await checkTranslationFiles('./locales', { target: 'en' });
result.success; // false
result.issues; // every issue, with its level, key, locale and file

// Check data you already have, with no file system work at all.
analyzeTranslations({ locales: { en, ko } }, { target: 'en' });

// Read a directory once, then check it as often as you like.
const session = await loadTranslations('./locales', { target: 'en' });
session.set('ko', 'desc.hello', '안녕하세요'); // → the issues for that key

// Or let your own application own the values and ask only for a verdict.
createAnalyzer({ target: 'en' }).checkEntry({
	key: 'desc.hello',
	values: { en: 'Hello {name}', ko: '안녕하세요' }
});
// [{ code: 'NO_INTERPOLATION_KEY', level: 'error', locale: 'ko', ... }]

analyzeTranslations and createAnalyzer do no file system work and are also published as chki18n/core, which imports no Node built-in and bundles for a browser or an editor's renderer process.

The documentation site covers every check, every option and how to render a result.

Contributing

Anyone can contribute by reporting an issue or opening a pull request. See CONTRIBUTING.md.

License

Released under the MIT License.