Documentation

Keep every locale file in step with your source.

verbatra translates your i18n locale files incrementally: it sends only the new and changed strings to the provider you configure, checks every result, and writes the files back in place.

npm i -D @verbatra/cli
Quick startCLI reference
~/acme-shop

An example verbatra command-line session.

  1. verbatra init
    • ✓ created verbatra.config.ts
    • source en · targets de, es, fr
    • provider gemini · key from GEMINI_API_KEY
  2. 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
  3. 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
  4. verbatra watch
    • watching en.json for changes
    • en.json changed · 1 new key
    • de 1 translated · 0 withheld
    • ✓ 3 keys translated · waiting for changes

Where to go next

New hereYour first translationInstall the CLI, scaffold a config, set your key, and translate.Already set upAdd a languageDrop a locale into your config and let one run fill it in.Under the hoodHow it worksThe pipeline: diff against the lock baseline, translate, verify, write.With an AI agentSet up with AIPoint Claude Code, Cursor, or any coding agent at a copy-pasteable prompt.

What verbatra does

Hand-maintaining one source locale means every other locale file drifts: new keys go missing from the targets, edited strings leave stale translations behind, and deleted keys linger as orphans. verbatra closes that gap by diffing every target against a committed lock file, verbatra.lock.json, and sending only what changed to the provider you configure; a second run with nothing new to translate makes no provider call at all. Every result is checked before it is written, so a broken placeholder is withheld and retried, never shipped. See How it works for the full pipeline.

verbatra reads and writes twelve formats and translates through six providers behind one interface. See Formats and Providers.

The packages

@verbatra/cli

The verbatra binary: ten commands, a thin wrapper over the SDK. Start here.

@verbatra/sdk

The engine underneath: translate, watch, check, diff, doctor, plus the Excel workbook round-trip.

@verbatra/studio

A local dashboard with built-in editing and a review queue. Provider spend stays off unless you opt in.

@verbatra/mcp

A stdio MCP server exposing translation status, glossary, and editing tools to an MCP client.