Translate only what changed.
verbatra is a CLI and SDK that keeps your i18n locale files in sync. You maintain the source locale; it fills every other locale through the AI provider you choose.
pnpm add -D @verbatra/cli
An example verbatra command-line session.
- verbatra init
- ✓ created verbatra.config.ts
- source en · targets de, es, fr
- provider anthropic · key from ANTHROPIC_API_KEY
- verbatra translate
- diff en.json · 12 new · 0 changed · 108 unchanged
- de 12 translated · 108 unchanged · 0 withheld
- es 12 translated · 108 unchanged · 0 withheld
- fr 12 translated · 108 unchanged · 0 withheld
- ✓ 36 keys translated in 5.4s · 0 skipped · lock updated
- verbatra diff
- en.json · 120 keys · source of truth
- de 2 new · 1 changed · 117 up to date
- es 0 new · 0 changed · 120 up to date
- fr 5 new · 0 changed · 115 up to date
- 8 keys would be sent · run verbatra translate to apply
- verbatra watch
- watching en.json for changes
- en.json changed · 1 new key
- de 1 translated · 0 withheld
- es 1 translated · 0 withheld
- fr 1 translated · 0 withheld
- ✓ 3 keys translated · waiting for changes
One tool for the whole translation loop.
verbatra is more than AI translation. It covers machine translation you control, a clean Excel handoff for human translators, and the automation to keep every locale in sync.
AI translation
Translate only what changed through your choice of provider: Anthropic, OpenAI, Gemini, DeepL, or any OpenAI-compatible server you run yourself. A committed lock file keeps every run incremental, and placeholder and ICU integrity is checked before anything is written.
Excel handoff
Run verbatra export to produce a styled .xlsx workbook, hand it to a translation office or in-house translators, then verbatra import reads their edits back into your locale files. Mix machine translation with professional human work.
Automation
Keep every locale in sync as you work: verbatra watch translates on change, CI-friendly exit codes and --json output slot into any pipeline, and a GitHub Action runs it in your workflow.
One tool, every framework.
verbatra reads the locale files your stack already uses: JSON for i18next, vue-i18n, next-intl, and ngx-translate, plus XLIFF, YAML, and Flutter ARB. It fills them through the provider you choose, no new format to adopt.
- Frameworks and formats:
- React
- Next.js
- Vue
- Nuxt
- Angular
- Node.js
- SvelteKit
- Astro
- React Native
- Flutter
Translate through the model you trust.
Anthropic, OpenAI, Gemini, DeepL, or any OpenAI-compatible server you host yourself. Pick one in a single line of config and switch providers without touching your locale files.
- Translation providers:
- Anthropic
- OpenAI
- Gemini
- DeepL
A run is a short, predictable pipeline.
No magic, no background sync: a deterministic sequence you can read top to bottom.
- 01
Configure
Point verbatra at your source locale, list the target languages, and pick a provider. Configuration lives in one file; API keys stay in your environment.
- 02
Diff
Each run compares your source locale against the committed lock file and sorts every key into new, changed, unchanged, or orphaned.
- 03
Translate
Only the new and changed keys are sent to your provider, in batches, with your glossary and tone applied. Everything else is left untouched.
- 04
Verify & write
Placeholder and ICU integrity are checked on every result. Anything that breaks is withheld; the rest is written to your locale files and the lock is updated.
Built for teams that ship in many languages.
Every choice favors predictability: small diffs, explicit config, and nothing written that was not verified first.
Incremental by default
A committed lock file records what was translated. Each run diffs the source and calls the provider only for the keys that changed.
Your choice of provider
Anthropic, OpenAI, Gemini, DeepL, or a local OpenAI-compatible model, chosen in one line of config. Switch providers without touching your locale files.
Safe by construction
Placeholder and ICU integrity are checked after every translation. A result that breaks a placeholder is withheld, never written.
Keys stay in your environment
Provider API keys are read from environment variables, never from the config file, never from CLI arguments, and never logged.
CLI and SDK, one engine
The verbatra command and @verbatra/sdk share a single orchestration core, so scripts, CI, and your own tooling behave identically.
Dry runs and watch mode
Preview exactly what a run would change without writing anything, or keep a watch running that translates as your source locale evolves.
Frequently asked questions
Short, direct answers to the questions teams ask before adopting verbatra.
It keeps a committed lock file that records what was already translated. Each run diffs your source locale against that lock and sends only the new or changed keys to your provider. Unchanged keys are never touched, so a typical run costs a handful of strings, not your whole catalog.
Five, behind one interface: Anthropic, OpenAI, and Gemini (LLMs), DeepL (machine translation), and openai-compatible, which points verbatra at a local or self-hosted server like Ollama, LM Studio, or vLLM. You pick one by id in your config and can switch later by editing that one line. Gemini has a real free tier, and a local model costs nothing per call.
JSON for i18next, vue-i18n, next-intl, and ngx-translate, plus XLIFF, YAML, and Flutter ARB. That covers React, Next.js, Vue, Nuxt, Angular, SvelteKit, Astro, Node.js, and Flutter. verbatra reads the files you already have; there is no verbatra-specific format to migrate to.
A local web dashboard over your project that shows every locale's status live, surfaces a review queue of flagged entries, and lets you fix translations in place. Start it with verbatra studio (install @verbatra/studio first). Editing your own locale files works out of the box; calling a provider from the UI is opt-in behind --allow-spend. It runs on 127.0.0.1 only and never leaves your machine.
Every result passes a placeholder and ICU integrity check before it is written. A translation that drops, invents, or reorders a placeholder, or produces invalid ICU message syntax, is withheld rather than saved to your locale file. The same gate applies to edits and retranslations made in Verbatra Studio.
Keys are read only from environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPL_API_KEY), never from the config file, CLI arguments, or logs. Only the strings you are translating are sent, and only to the provider you chose. If you use the openai-compatible provider with a local model, nothing leaves your machine or network at all.
Yes. A dry run reports exactly which keys would be sent and written without touching your files, and verbatra check and verbatra diff report per-locale drift without calling a provider. Watch mode does the opposite: it keeps translating as your source locale changes.
Yes. The CLI is a thin wrapper over @verbatra/sdk, which exposes the same translate, watch, check, and diff operations for your own tooling. Commands return CI-friendly exit codes and support --json output, and an official GitHub Action runs verbatra in your workflow.
verbatra itself is free and open source under the MIT license. The only cost is your provider's usage, which you control: it translates only what changed, and you can run it for free on Gemini's free tier or a local OpenAI-compatible model.
It is young and actively developed, so pin a version and read the changelog when you upgrade. The safety model is already solid: every run diffs against a committed lock file, checks placeholder and ICU integrity on each result, and withholds anything that breaks rather than writing it. Teams run it in CI today; pin versions and you are on stable ground.
Stop hand-syncing locale files.
Add verbatra, commit the lock file, and let every run touch only what changed.