i18n-toolkit

AST-based CLI to extract translation keys from a React / Next.js project, diff them against translation resource files, and translate the missing ones via a local Ollama instance.

Install

# global
npm install -g @syedamirali/i18n-toolkit

# or one-shot via npx (no install)
npx @syedamirali/i18n-toolkit extract --src ./src

Requires Node ≥ 20. For translate you also need a running Ollama instance.

Commands

| Command | Purpose | |---|---| | i18n-toolkit extract | Scan source for translation keys | | i18n-toolkit diff | Compare extracted keys against a translation file | | i18n-toolkit translate | Translate missing keys via Ollama | | i18n-toolkit help | Show top-level help |

i18n-toolkit extract

i18n-toolkit extract --src /path/to/your/app/src

Output: i18n-toolkit/output/{timestamp}_translation_extractor.json — sorted, deterministic.

What it matches (all AST-based, no regex):

| Source | → | |---|---| | t("k", { __default__: "v" }) | { "k": "v" } | | t("k") \|\| "fallback" | { "k": "fallback" } | | t("k") | { "k": "__missing_default__" } | | <Trans localKey="k">Default</Trans> | { "k": "Default" } | | <X localKey={\a.${slug}.b`}>{name}` | { "a.${slug}.b": "__dynamic__" } |

Key options:

--src <path>             root to scan (default ".")
--out <path>             explicit output file (overrides --output-dir)
--output-dir <path>      default ./i18n-toolkit/output
--log-dir <path>         default ./i18n-toolkit/logs
--lang <code>            top-level language key (default "en")
--fail-on-conflict       exit 1 if any key has conflicting defaults
--help                   full options list

i18n-toolkit diff

# Scriptable
i18n-toolkit diff --src /path/to/app/src --resource ./translations.json

# Interactive
i18n-toolkit diff

--src accepts either a directory (runs extraction in-process) or a previously-extracted JSON file. --resource auto-detects flat { key: value } vs language-wrapped { "en": { … } } and picks the en slice.

Output: i18n-toolkit/diff-output/{timestamp}/

| File | What's in it | |---|---| | missing_in_resource.json | Keys present in code, missing from resource — translate these | | missing_in_extractor.json | Keys present in resource, no longer in code — orphans | | {timestamp}_translation_diff.log | Run log with absolute paths |

"__dynamic__" keys are skipped from comparison. Empty "" values in either side are treated as missing.

i18n-toolkit translate

i18n-toolkit translate

Interactive. Three steps:

1. Input — pick a recent missing_in_resource.json, paste a path, or paste content inline.
2. Target languages — searchable multi-select from data/languages.json. The source (en) is shown at the top, pinned and disabled.
3. Model — pick from your local Ollama's installed models.

The Ollama call streams with live thinking + response phases and a sticky status footer (elapsed / tokens / KB).

Output: i18n-toolkit/translate-output/{timestamp}/translation.json

{
  "en": { "common.back": "Back",   "common.cart": "Cart"   },
  "fr": { "common.back": "Retour", "common.cart": "Panier" },
  "ar": { "common.back": "رجوع",   "common.cart": "عربة"   }
}

Env vars:

OLLAMA_URL           default http://172.25.80.1:11434
OLLAMA_TIMEOUT_MS    default 1800000 (30 min)
NO_COLOR             disable ANSI colors

Pipeline

The three commands compose:

your-app/src/  ──extract──▶  i18n-toolkit/output/…json
                                       │
                                       ▼
   resource.json  ──diff──▶  i18n-toolkit/diff-output/…/missing_in_resource.json
                                                              │
                                                              ▼
                                     translate ──▶  i18n-toolkit/translate-output/…/translation.json

All four output directories live under a single i18n-toolkit/ workspace folder in your project root, so you only have one entry to ignore (i18n-toolkit/) — and the tool actually drops an auto-generated i18n-toolkit/.gitignore for you on first run, so you don't even have to do that.

Drop the final translation.json back into your app's translation resource and the cycle closes.

Local development

Clone the repo, install dependencies, and use the yarn aliases:

git clone https://github.com/SyedAmirAli/i18n-toolkit.git
cd i18n-toolkit
yarn install

yarn extract -- --src /path/to/your/app/src
yarn diff -- --src /path/to/app/src --resource ./translations.json
yarn translate

yarn build       # bundle to dist/ (used by npm publish)
yarn typecheck   # tsc --noEmit

Project structure

src/
├── cli.ts           subcommand router (the published bin entry)
├── index.ts         extract command + runExtraction() programmatic API
├── diff.ts          diff command
├── translate.ts     translate command
└── lib/
    └── ui.ts        Spinner, StatusFooter, JsonPretty, multilineInput, color helpers
prompt/              prompt template used by translate
data/                language list used by translate
docs/plans/          design docs (one per command)
dist/                bundled output (generated; not in git)

All generated artifacts go under i18n-toolkit/ (auto-gitignored): output/, logs/, diff-output/, translate-output/.

Design docs

See docs/plans/ for the full design behind each command.

| Plan | Command | |---|---| | 01-translation-extractor.plan.md | extract | | 02-translation-diff.plan.md | diff | | 03-translate.plan.md | translate | | 04-translate-quality.plan.md | translate quality detection (planned) |

License

MIT © Syed Amir Ali