i18n-unused

The library provides specific types to represent the results of its analysis.

Unused Translations

When checking for unused keys, the result is returned as UnusedTranslations:

• translations: An array of UnusedTranslation objects. Each object contains:
  • localePath: The path to the locale file.
  • keys: An array of the unused keys found.
  • count: The number of unused keys in that file.
• totalCount: The total number of unused keys across all files.

Missed Translations

When checking for keys used in code but missing from locales, the result is returned as MissedTranslations:

• translations: An array of MissedTranslation objects. Each object contains:
  • filePath: The path to the source file where the key was found.
  • staticKeys: Keys found via static analysis.
  • dynamicKeys: Keys found via dynamic analysis.
  • staticCount: Count of static keys.
  • dynamicCount: Count of dynamic keys.
• totalStaticCount: Total static keys missed across all files.
• totalDynamicCount: Total dynamic keys missed across all files.

Use the collectMissedTranslations async function to find keys that are used in your source code but are missing from your translation files. It distinguishes between staticKeys (without ${} syntax) and dynamicKeys (with ${} syntax).

Return Shape:

{
  "translations": [
    {
      "filePath": "src_file_path",
      "staticKeys": ["missed_key"],
      "dynamicKeys": ["missed_key"],
      "staticCount": 1,
      "dynamicCount": 1
    }
  ],
  "totalStaticCount": 1,
  "totalDynamicCount": 1
}

import { collectMissedTranslations } from 'i18n-unused';

const handleTranslations = async () => {
  const missedTranslations = await collectMissedTranslations(
    localesPaths, // paths to locale files
    srcFilesPaths, // paths to src files
    {
      localeFileParser: (module) => module, // optional, resolver for module
      excludeTranslationKey: ['.props.'], // optional, special string or sting[] to exclude flat translations
      translationKeyMatcher: /(?:[$ .](_|t|tc))\(.*?\)/ig, // optional, match translation keys in files
    },
  );
};

The RunOptions interface defines the configuration for running the unused and missed translation checks. You can use these options to customize how locales are loaded, how source files are scanned, and how translation keys are matched.

Key Configuration Categories

Locales Configuration

• localesPath: Path to your locales folder.
• localesExtensions: Allowed file extensions for locales (defaults to ['json'] if localeNameResolver is not set).
• localeNameResolver: A ModuleNameResolver (RegExp or function) to resolve locale names from filenames.
• localeFileParser: A ModuleResolver to handle locale imports (defaults to (m) => m.default).
• localeFileLoader: A CustomFileLoader to manually load locale files.

Source Scanning

• srcPath: Path to search for translations (defaults to process.cwd()).
• srcExtensions: Allowed file extensions for source files (defaults to ['js', 'jsx', 'ts', 'tsx', 'vue']).
• ignorePaths: Array of paths to ignore (must start similarly to srcPath).
• ignoreComments: Whether to ignore code comments in source files (defaults to false).
• excludeKey: A string or array of strings. If a translation key includes these, it will be ignored (e.g., '.props.' ignores Button.props.value).

Translation Matching

• translationKeyMatcher: A TranslationKeyMatcher (RegExp) to find translation keys in code (defaults to matching $_, $t, t, $tc, tc, and i18nKey).
• translationSeparator: The separator used for translation keys in code (defaults to '.').
• missedTranslationParser: A MissedTranslationParser to extract keys from matches (defaults to matching values inside rounded brackets).
• context: Whether to use i18n context like plurals (defaults to true).
• translationContextSeparator: Separator for i18n context (defaults to '_').
• translationContextMatcher: RegExp to match i18n context keys (defaults to matching zero, one, two, few, many, other, male, female, 0, 1, 2, 3, 4, 5, plural, 11, and 100).

Execution Behavior

• failOnUnused: Throw an error if unused translations are found (defaults to false).
• failOnMissed: Throw an error if missed translations are found (defaults to false).
• marker: Special string used to mark unused translations (defaults to '[UNUSED]').
• localeJsonStringifyIndent: JSON indentation for writing files (defaults to 2).

The following options are available in the i18n-unused.config.js file to customize the analysis behavior.

| Option name | Description | Required | Type | Default value |
| --- | --- | --- | --- | --- |
| localesPath | path to search for locales | yes | string | - |
| localesExtensions | allowed file extensions for locales | no | string[] | if not set `localeNameResolver`: ['json'] |
| localeNameResolver | file name resolver for locales | no | RegExp, (name: string) => boolean | - |
| customChecker | function to check if a key is used, if so the key should be removed from translationsKeys | no | fn, (matchedKeys: Set<string>, translationsKeys: string[] => void) | A defined validations will be applied |
| localeFileParser | resolve locale imports, for example if you use named imports from locales files, just wrap it to your own resolver | no | (module) => module | fn, return `module.default` or `module` |
| localeFileLoader | load the locale file manually (e.g. for using your own parser) | no | (filePath) => object | - |
| srcPath | path to search for translations | no | string | `''` (same as run folder) |
| srcExtensions | allowed file extensions for translations | no | string[] | ['js', 'ts', 'jsx', 'tsx', 'vue'] |
| ignorePaths | ignored paths, eg: `['src/ignored-folder']`, should start similarly `srcPath` | no | string[] | - |
| translationKeyMatcher | matcher to search for translation keys in files | no | RegExp | RegExp, match `$_`, `$t`, `t`, `$tc`, `tc` and `i18nKey` |
| excludeKey | doesn't process translations that include passed key(s), for example if you set `excludeKey: '.props.'`, script will ignore `Button.props.value`. | no | string, string[] | - |
| ignoreComments | Ignore code comments in src files. | no | boolean | false |
| marker | special string to mark unused translations, it'll added via `mark-unused` | no | string | '[UNUSED]' |
| gitCheck | show git state change tree | no | boolean | false |
| context | use i18n context, (eg: [plurals](https://www.i18next.com/translation-function/context)) | no | boolean | true |
| flatTranslations | use flat translations, (eg: [Flat JSON](https://www.codeandweb.com/babeledit/documentation/file-formats#flat-json)) | no | boolean |
| translationSeparator | separator for translations using in code | no | string | '.' |
| translationContextSeparator | separator for i18n context (see `context` option) | no | string | '_' |
| translationContextMatcher | matcher to search for context endings | no | RegExp | RegExp, match `zero`, `one`, `two`, `few`, `many`, `other`, `male`, `female`, `0`, `1`, `2`, `3`, `4`, `5`, `plural`, `11` and `100` |
| missedTranslationParser | parser for ejecting value from `translationKeyMatcher` matches | no | RegExp, (v: string) => string | RegExp, match value inside rounded brackets |
| localeJsonStringifyIndent | json indent value for writing json file, either a number of spaces, or a string to indent with. (i.e. `2`, `4`, `\t`) | no | string , number | `2` |