@i18n-doctor/cli

Beta — v0.11.17 · GitHub · Issues

Static localization analysis for JavaScript and TypeScript projects.
Finds unused, missing, duplicate translation keys, and untranslated hardcoded UI text — without executing your code.

What's new in 0.11.17

• Windows scanner: keep distinct sources/locales when file indexes collide (no false hardlink drops)

What's new in 0.11.16

• Vite / Windows: resolve path aliases from tsconfig.app.json and extends
• Cross-file schema(t) namespace flow works with Windows path separators and casing

What's new in 0.11.15

• Shared catalog modules: usage in any sibling namespace on the same source file clears unused for all (settings ↔ map spreads)

What's new in 0.11.14

• Route tab titles via getRouteParam(..., "title") from *Route files (nested settings/children included)
• for…in t(key) over API maps keyed by string enums (e.g. IPropertyType) without inventing missing keys
• Spread-imported catalog keys underline the origin file, not the spreader
• Static catalog string concat ("a" + "b") in JS/TS sources

What's new in 0.11.13

• Live unused-key updates: deleting one unused key keeps remaining underlines (no long rescan gap)
• Broader static usages: factory configs, useMemo menus, remapped labels, prefixed FILTER_OPERATOR_* templates
• Assigned-then-returned enum arrays; JSX helper prop indexing after helpers

What's new in 0.11.11

• Inline i18next resources maps: same key in en/fa is not a duplicate

• Nested translation objects under locale maps are not double-extracted

• Path-alias imports (app/*, @core/*) for translator factories and configs

• Store/object methods with t params; renamed Zustand selectors

• Multi-namespace addResourceBundle on one shared i18n module

• String-literal array maps, enum-typed t(type as string), labelKey / config lookups

• i18n.t("KEY", { ns }), JSX Object.keys(Enum) → child t(item), enum helper arrays

• buildPayload({ t }) namespace flow; t(data.actionType) / nested enum property access

Install & run

# Run without installing
npx i18n-doctor check

# Install globally
npm install -g @i18n-doctor/cli
i18n-doctor check

Usage

i18n-doctor check [path] [options]

Options:
  --dir <path>    Analyze only files under this directory (relative to project root)
  --json          JSON report
  --sarif         SARIF 2.1.0 report
  --markdown      Markdown report
  --html          HTML report
  --silent        Exit code only, no output
  --verbose       Show timings
  --config        Path to config file
  --locale        Restrict to one locale
  --namespace     Restrict to one namespace
  --base-locale   Base locale for cross-locale coverage
  --no-coverage   Skip locale consistency analysis

Check one folder

Pass a subdirectory as [path], or use --dir from the project root:

# Only report issues in src/features/auth (still loads locale catalogs project-wide)
i18n-doctor check src/features/auth

i18n-doctor check --dir src/features/auth

Missing-key and untranslated findings are limited to code under that folder. Locale files outside the folder are still read so missing-key checks stay accurate. Unused-key and duplicate-key findings only appear when the catalog file is inside the scoped directory.

Rules

Configure in i18n-doctor.config.json:

| Rule | Default | Meaning | | --- | --- | --- | | unused-key | warning | Locale key never referenced in code | | missing-key | error | Code uses a key missing from locale files | | duplicate-key | warning | Key defined more than once | | untranslated-text | info | Hardcoded UI text not passed through t() / similar |

Example:

{
  "rules": {
    "untranslated-text": "warning",
    "unused-key": "error"
  }
}

Exit codes

| Code | Meaning | |---:|---| | 0 | No failing issues | | 1 | Issues found that fail the exit policy | | 2 | Config, I/O, or permission error |

Contributing

This is a beta release. Bug reports, feature requests, and pull requests are very welcome.
See the GitHub repo to get started.

License

MIT