better-i18n.com
DocumentaciónCentro de ayudaNovedades

How do I use i18n Doctor to check translation health?

Actualizado el Aug 21, 2026

Doctor gives your project a health score out of 100 and tells you what is dragging it down. It runs from the CLI, and it can send the result to your dashboard so the score has a history instead of scrolling past in a terminal.

Run it #

Bash
better-i18n doctor

It does three passes:

PassLooks atSkip with
Code analysisYour source, via AST — which keys you actually use--skip-code
File healthYour translation files — placeholders, structure--skip-health
Remote comparisonYour project on the CDN versus local--skip-sync

Skipping is useful when one pass is slow or noisy — a monorepo where the AST walk takes a while, or a machine with no network.

What it catches #

Missing translations — keys with no value in a language.

Orphan keys — keys in your project that no code references. Not automatically wrong: dynamically built key names are invisible to a static scan, so read the list before deleting anything.

Placeholder mismatches — the check worth having. If English says {count} and Turkish dropped it, the words look fine and the string is broken. Reviewers skim past this; a diff of placeholder sets does not.

In CI #

Bash
better-i18n doctor --ci

--ci exits non-zero when the health score falls below its threshold — it is a score gate, not a "fail if anything is missing" flag. That is the difference that matters in a pipeline: one newly added untranslated key does not block a deploy, a project sliding backwards does.

YAML
- name: i18n health
  run: better-i18n doctor --ci
  env:
    BETTER_I18N_API_KEY: ${{ secrets.BETTER_I18N_API_KEY }}

JSON output for anything that needs to parse it:

Bash
better-i18n doctor --format json

Send the report to your dashboard #

Bash
better-i18n doctor --report

That uploads the run to Integrations → Doctor, where you get the score, the four dimensions behind it — coverage, quality, structure, code — and a log of previous reports.

The reason to bother: a number in your terminal tells you today's state, a series tells you which direction you are going. Run it in CI with --report and the trend appears without anyone maintaining it.

Fixing what it finds #

FindingFix
Keys in code, not in your projectbetter-i18n sync --push
Missing translationsEditor's Only missing filter, or bulk AI translation
Placeholder mismatchEdit the value — the editor highlights placeholders, so it is visible
Orphan keysCheck for dynamic usage first, then delete in the editor

There is no delete-unused command and no doctor block in your config: the options above are the whole surface, which keeps the report and the flags honest about each other.