Internationalization (i18n) breaks quietly. Keys rot in locale files. Screens ship with English hardcoded in JSX. Another locale is missing half the catalog. Most teams only notice this in production — or never.
i18n-doctor is an open-source static analyzer for JavaScript and TypeScript that finds those problems without running your app.
One-line definition: i18n-doctor checks your source and locale files for unused keys, missing keys, duplicates, cross-locale gaps, and untranslated UI text — then reports them in the CLI or live in your editor.
The problem i18n-doctor solves
Modern frontends rarely call
t("key")in one simple place. Keys are:
- passed down as props (
{ t },props.t)- built from static pieces (
"HELLO_" + "AGAIN")- partly dynamic (
t("HELLO_" + suffix))- mixed across React, Vue, Angular, Next.js, i18next, react-intl, vue-i18n, next-intl, Lingui, and more Regex scripts and “search the repo” workflows miss those patterns. Manual review does not scale. Locale files grow, CI stays green, and translation debt compounds. ## Why I built it I kept hitting the same gap: great i18n libraries, but weak hygiene tooling that understands real usage — including IDE feedback while you type, not only a CI script after the fact. So I built i18n-doctor as:
- a CLI you can run with
npxor in CI- a shared language server
- thin VS Code and JetBrains / WebStorm plugins on top of that server Same analyzer everywhere — terminal, PR checks, and the editor.
What it detects today
| Finding | Meaning |
|---|---|
| Unused keys | Defined in locales, never referenced in code |
| Missing keys | Used in code, missing from locales |
| Duplicate keys | Same key defined more than once |
| Cross-locale gaps | Present in one locale, absent in another |
| Untranslated text | Hardcoded JSX / UI strings that never go through a translator (info by default) |
It also handles harder static cases:
- prop-passed translators
- statically concatenated keys
- soft “may be unused” hints when a dynamic usage might still cover a key Analysis is static only — no runtime, no bundler, no side effects. ## Try it in 10 seconds
npx i18n-doctor check
Or install as a dev dependency and wire a script:
npm install -D i18n-doctor
# package.json → "i18n:check": "i18n-doctor check"
And the result:
· Discovering project…
· Loading configuration…
· Detecting framework…
· Collecting sources & usages…
· Analyzing locale coverage…
✓ Done (2376ms)
i18n-doctor issues
Root: PATH/TO/YOUR/PROJECT
Summary
Unused: 1152
Missing: 34
Duplicate: 3
Total: 1189
Locale coverage
Base: en Locales: en, fa
Coverage: 99.56%
Missing in other langs: 18
Extra (not in base): 17
en 100% (2040/2040 keys)
fa 99.1% (2022/2040 keys)
"and the unused or duplicated keys locations here"
Prefer live underlines while editing? Install the editor extension (bundled language server — no project dependency required):
- VS Code Marketplace → search i18n-doctor
- JetBrains Marketplace → search i18n-doctor
Development path (where this is going)
i18n-doctor is currently in beta (v0.9.x). The path so far:
- Core analyzer — unused / missing / duplicate / coverage
- CLI + reports — terminal, JSON, SARIF, Markdown, HTML
- Language server — shared engine for editors
- VS Code + JetBrains plugins — live diagnostics
-
Smarter usages — prop-passed
t, static composition, dynamic softening, untranslated UI text Next focus areas: more frameworks and edge cases, better suppressions/config ergonomics, and IDE features beyond diagnostics (hover / actions) when the analyzer is solid enough. Feedback from real projects is the fastest way to stabilize toward v1. ## Who should use it - Teams shipping multi-locale React / Vue / Next / Angular apps
- Maintainers cleaning up large locale JSON / catalogs
- Anyone who wants i18n checks in CI and the editor from one tool If your translations matter to users, your keys deserve the same static scrutiny as TypeScript types. ## Links
- GitHub: https://github.com/taha-farzalizadeh/i18n-doctor
- npm (
i18n-doctor/ CLI): https://www.npmjs.com/package/i18n-doctor - Issues / feedback: https://github.com/taha-farzalizadeh/i18n-doctor/issues
- VS Code extension: search i18n-doctor on the Visual Studio Marketplace
- JetBrains / WebStorm plugin: search i18n-doctor on the JetBrains Marketplace If you try it on your repo, open an issue with what it missed — that feedback shapes the beta. ---
Top comments (1)
nice