Introduction

Better i18n CLI helps you manage the entire lifecycle of your translation keys — from detecting hardcoded strings to auditing remote sync status. Run a single command to get a full health report, or use focused commands for specific tasks.

Commands

`doctor` — Full i18n health report

The most powerful command. Runs five analysis layers in a single pass and gives your project a health score from 0–100.

better-i18n doctor

╭──────────────────────────────────────────────╮
│                                              │
│   🌐 better-i18n  ·  i18n Doctor Report  │
│   hello · hola · 你好 · こんにちは · 안녕    │
│                                              │
├──────────────────────────────────────────────┤
│  ████████████████░░░░ 82 / 100 A       │
│  PASSED (threshold: 70)           │
╰──────────────────────────────────────────────╯

Category Scores:
  Coverage       95 (3 issues)
  Quality        88 (2 issues)
  Code           72 (8 issues)
  Structure     100 (clean)
  Performance    91 (1 issues)

What doctor checks:

Category	What it finds
Code	Hardcoded strings not wrapped in `t()`
Coverage	Keys missing from target locales
Quality	Placeholder mismatches across locales
Performance	Orphan keys that exist in translations but are unused in code
Sync	Keys missing from or extra in the remote CDN

Use --ci to fail the build when the score drops below the pass threshold. Use --report to upload results to the Better i18n dashboard for tracking over time.

View full doctor documentation →

`scan` — Hardcoded string detection

Find user-facing strings that are not yet wrapped in t(). Supports --staged for pre-commit hooks.

better-i18n scan

components/sign-up.tsx (3)
  24:13  missing  "Create an account"  i18n/jsx-text
  32:22  missing  "Name"               i18n/jsx-text

✖ 87 problems (87 missing translations)

View full scan documentation →

`check` — Interactive key checker

Focused, interactive checker for missing or unused translation keys. Guides you through what to check with prompts.

better-i18n check

? What would you like to check?
  ❯ Missing translation keys
    Unused translation keys
    Both (Full Comparison)

View full check documentation →

`sync` — Full local ↔ remote comparison

Compare all t() calls in your code against the Better i18n remote and see both missing and unused keys at once. Best for CI or full audits.

better-i18n sync

View full sync documentation →

`content:types` — Generate TypeScript from content models

Generate typed interfaces from your Content CMS models — like supabase gen types typescript. Auto-loads API key from .env.

better-i18n content:types

✓ Project: acme/landing
✓ Found 3 content model(s)
✓ Content types generated
  Output: src/content-types.ts
  Models: blog-posts, changelog, pricing-plans

View full content:types documentation →

`pull` — Download translations for offline fallback

Download translations from CDN to local JSON files. Essential for mobile apps (Expo, React Native) where bundled translations ensure the app works even when the CDN is unreachable — including during App Store Review.

better-i18n pull

✔ Project: acme/my-app
✔ Manifest: 3 languages (en, de, tr)
✔ Downloaded 3 locale(s) to locales/

  ✓ en      1867 keys  145.8 KB
  ✓ de      1742 keys  146.3 KB
  ✓ tr      1741 keys  131.0 KB

View full pull documentation →

When to use which command

I want to…	Command
Get a full project health score	`doctor`
Download translations for mobile offline fallback	`pull`
Block CI on i18n regressions	`doctor --ci`
Catch hardcoded strings before commit	`scan --staged --ci`
Quickly check if new keys are uploaded	`check:missing`
Clean up unused translations	`check:unused`
See full missing + unused comparison	`sync`
Generate types for Content CMS models	`content:types`

Installation

# With npx (no install needed)
npx @better-i18n/cli doctor

# Or install globally
npm install -g @better-i18n/cli

Features

✅ Health Score — Single 0–100 score with per-category breakdown and CI pass/fail threshold.
✅ Lexical Scope Tracking — Smart namespace detection for both useTranslations and getTranslations.
✅ Server Component Support — Full support for Next.js App Router async server functions.
✅ CI/CD Ready — Enforce key coverage and health score in your pipeline.
✅ Smart Filtering — Automatically ignores CSS, URLs, and developer constants.
✅ Verbose Audit Log — Deep transparency with --verbose on any command.

Cmd+Click on any file path in the terminal to jump directly to the code in VS Code!

On this page