i18n Doctor: Get a Full Translation Health Report in One Command
Run better-i18n doctor to analyze your entire codebase across five dimensions — code quality, translation coverage, placeholder accuracy, orphan keys, and CDN sync — and get a single 0–100 health score with actionable diagnostics.
Five Analysis Layers in a Single Pass
Doctor runs code scanning, coverage analysis, quality verification, performance auditing, and CDN sync checks — all at once, with a unified score.
Code — Hardcoded String Detection
AST-based scanning finds every user-facing string not wrapped in t(). Catches JSX text, attributes, ternary locale logic, toast messages, and string variables.
Coverage — Missing Translations
Compares keys present in your source locale against each target locale. Any key missing from a target locale is reported with its exact namespace and path.
Quality — Placeholder Mismatch
Verifies interpolation placeholders are consistent across all locales. Supports named {}, double-brace {{}}, printf %s, template ${}, and positional {0} formats.
Performance — Orphan Key Detection
Detects keys that exist in your translation files but are never referenced in code. Orphan keys increase payload size and create maintenance debt.
Sync — CDN Comparison
Compares keys extracted from your code against published keys in the CDN. Surfaces missing-in-remote and unused-remote-key issues before they hit production.
A Single Score for Your Translation Health
Doctor computes a score from 0 to 100 based on the diagnostics found. Errors are penalized at 3.0 points each, while each rule's warning contribution is capped at 20 points — preventing a single rule with thousands of warnings from zeroing your entire score.
The default pass threshold is 70 (grade B). Use --ci to fail builds below this threshold, or start with --report to establish a baseline before enforcing the score.
score = 100 - (errors × 3.0) - Σ min(rule_warnings × 0.15, 20)Grade Thresholds
CI/CD Integration — Block Bad Translations Before They Ship
Add doctor to your CI pipeline to catch translation regressions on every push. Automatic OIDC auth in GitHub Actions means zero secret management.
GitHub Actions with OIDC
Authenticate automatically without API keys using GitHub Actions OIDC. Just add id-token: write permission and run doctor --ci --report.
Threshold Gating
Set a pass threshold (default: 70) and fail the build when the score drops below it. Start tracking with --report, then enforce with --ci.
Machine-Readable JSON
Use --format json for structured output you can pipe into jq, custom dashboards, or downstream automation in your deployment pipeline.
Dashboard Reporting
Upload results to the Better i18n dashboard with --report for historical tracking, trend analysis, and team-wide visibility into i18n health.
When to Use Which Command
Doctor is the comprehensive option. Use focused commands when you need a specific check or want faster feedback in pre-commit hooks.
doctorFull health score with five analysis layers — the single source of truth for your project's i18n status.
scanFocused hardcoded string detection. Supports --staged for pre-commit hooks.
checkInteractive checker for missing or unused translation keys with guided prompts.
syncFull local-to-remote comparison showing both missing and unused keys at once.
Built for Real-World i18n Workflows
Health Score 0–100
Single score with per-category breakdown and CI pass/fail threshold. Track your translation health over time.
Lexical Scope Tracking
Smart namespace detection for both useTranslations and getTranslations. Every t() call maps to its correct namespace.
Server Component Support
Full support for Next.js App Router async server functions. Server-side getTranslations calls are detected and audited.
Configurable Rules
Disable or downgrade rules in i18n.config.ts. Set rules to "error", "warning", or "off" to match your project's needs.
Smart Filtering
Automatically ignores CSS class names, URLs, import paths, and developer constants. Only actionable results.
Verbose Audit Log
Deep transparency with --verbose. Scoping summaries, timing information, and namespace resolution traces for debugging.
Related Topics
CLI & Code Scanning
AST-based hardcoded string detection and code scanning tools
For Developers
Developer-focused i18n tools with type-safe SDKs and Git-first workflows
Localization Software
Platforms and software for managing localization at scale
Translation Management
Centralized platform for managing translation workflows at scale
Know Your Translation Health Before You Ship
Run better-i18n doctor once to get your baseline. Add it to CI to never ship missing translations again.