i18n-check

By default, i18n-check validates against missingKeys and invalidKeys. You can restrict the execution to specific checks using the --only (or -o) flag.

Available check types:

• invalidKeys: Finds translations that are syntactically incorrect (e.g., invalid ICU messages).
• missingKeys: Finds keys present in the source locale but missing in target locales.
• unused: Finds keys present in translation files that are not used in the source code.
• undefined: Finds keys present in translation files that are not used in the source code (often used interchangeably with unused depending on context).

Note: The --check flag is deprecated; use --only instead.

A CheckResult represents the outcome of the i18n validation process. It is a record where keys are the identifiers (such as translation keys or file paths) and values are arrays of error messages associated with those keys.

// Example structure of a CheckResult
const result: CheckResult = {
  'common.welcome': ['Missing translation in es.json'],
  'errors.not_found': ['Invalid ICU pattern']
};

When using Options, you can provide an ignore array to skip specific keys during validation. The library supports exact matches and simple suffix-based globbing.

• Exact match: 'my_key' will ignore only my_key.
• Suffix glob: 'prefix_*' will ignore any key that starts with prefix_ (e.g., prefix_button, prefix_label).

When identifying specific invalid entries within translations, the tool uses InvalidTranslationsResult. This maps a context (like a file or language) to an array of InvalidTranslationEntry objects, which contain the specific key that failed and the error msg.

// Example structure of InvalidTranslationsResult
const invalidResults: InvalidTranslationsResult = {
  'en.json': [
    { key: 'auth.login', msg: 'Expected string, got number' }
  ]
};

To detect keys that are defined in your translation files but never actually called in your application code, use the --unused flag followed by the paths to your source files (e.g., .js, .jsx, .ts, .tsx).

When performing this check, you can provide additional context to the parser:

• --parser-component-functions <components...>: A list of component names to parse when scanning for usage.
• --next-intl-translation-fn-type-alias <nextIntlTranslationFnTypeAliases...>: Specific type aliases for next-intl translation functions.

Example:

i18n-check -l locales/ -s en -u src/ --only unused

You can control how the results are displayed using the --reporter flag:

• standard (default): Displays detailed tables for each type of error found (e.g., formatCheckResultTable, formatInvalidTranslationsResultTable).
• summary: Displays a condensed summary of the findings using formatSummaryTable.

The vitest.bin.config.ts file extends a base Vitest configuration to set up the testing environment specifically for the binary/CLI components of i18n-check. It inherits all settings from ./vitest.config and applies specific exclusions for the test runner to prevent scanning dependency or build directories.

import { defineConfig } from 'vitest/config';
import baseConfig from './vitest.config';

export default defineConfig({
  ...baseConfig,
  test: {
    exclude: ['node_modules', 'dist'],
  },
});

The Options type defines the configuration for the i18n-check process. You can specify the translation format, custom checks, files to ignore, and type aliases for next-intl translation functions.

Available format values:

• 'icu'
• 'i18next'
• 'react-intl'
• 'next-intl'

const options: Options = {
  format: 'i18next',
  ignore: ['**/node_modules/**'],
  checks: [], // Array of Context objects
  nextIntlTranslationFnTypeAlias: ['TFunction']
};

Use formatCheckResultTable to generate a detailed visual table showing exactly which files and keys contain issues. It takes a CheckResult object and returns a formatted string with 'file' and 'key' columns.

import { formatCheckResultTable } from './errorReporters.js';

const result = {
  'locales/en.json': ['auth.login.error', 'auth.logout.success']
};

const table = formatCheckResultTable(result);
console.log(table);