# verbatra > verbatra is a CLI and SDK that keeps your i18n locale files in sync, translating only the keys that are new or whose source text changed, through your choice of AI or machine-translation provider. verbatra is open source and MIT licensed. You maintain one source locale; on each run it diffs the source against a committed lock file and sends only the new or changed keys to your provider, leaving current translations untouched. Placeholder and ICU integrity are checked after every translation, and any result that breaks a placeholder is withheld. Written files round-trip in exact document order: existing keys keep their positions and new keys are appended in source order, so translated files diff cleanly. Suspicious results are flagged for review, and the local Studio dashboard (the `verbatra studio` command) shows project state, drift, and the review queue. - Repository: https://github.com/mariokreitz/verbatra - npm packages: @verbatra/cli (the `verbatra` command), @verbatra/sdk (programmatic API), @verbatra/studio (local review dashboard, loaded by `verbatra studio`) - Translation providers: Anthropic, OpenAI, Gemini, DeepL, openai-compatible (local or self-hosted) - i18n formats: i18next, vue-i18n, next-intl, ngx-translate, Flutter ARB, YAML, XLIFF, and Java/Spring properties - Frameworks: React, Vue, Angular, Node.js, Flutter - Requires Node.js >= 22.14.0 ## Introduction - [Introduction](https://verbatra.kreitz-webdev.de/docs): What verbatra is, the problem it solves, and how the CLI, SDK, and Studio fit together. Translate only the keys that changed, with integrity checks on every result. ## Get started - [Your first translation](https://verbatra.kreitz-webdev.de/docs/your-first-translation): Install the CLI, scaffold a config with verbatra init, set your API key, and run your first translate. Under ten minutes from nothing to a translated locale file. - [Add a language](https://verbatra.kreitz-webdev.de/docs/add-a-language): Add a new target locale to an existing verbatra project with a one-line config change and one translate run, while your existing locales stay untouched. ## Core concepts - [How it works](https://verbatra.kreitz-webdev.de/docs/how-it-works): The translation pipeline end to end, from reading the source locale to updating the lock file. - [The lock file](https://verbatra.kreitz-webdev.de/docs/the-lock-file): What verbatra.lock.json records, how drift is detected, how concurrent runs are serialized, and why you commit it. - [The cache](https://verbatra.kreitz-webdev.de/docs/the-cache): What verbatra.cache.json reuses, how a fingerprint scopes it, and why it never fails a run. - [Translation safety](https://verbatra.kreitz-webdev.de/docs/translation-safety): The safety model: untrusted strings, the integrity gate, review flags, the token budget, and errors that never leak. ## Configuration - [Config file](https://verbatra.kreitz-webdev.de/docs/config-file): Every config key with its type, default, and constraints, plus the discovery order and what happens when validation fails. - [Providers](https://verbatra.kreitz-webdev.de/docs/providers): The five translation providers, their options and API keys, and the behavior they all share. - [Formats](https://verbatra.kreitz-webdev.de/docs/formats): The eight supported formats, how each one reads and writes its files, and the document key order guarantee. ## Guides - [CI and exit codes](https://verbatra.kreitz-webdev.de/docs/ci-and-exit-codes): Gate a pipeline on translation state with check or diff, read the exit-code contract, and consume the JSON output. - [GitHub Action](https://verbatra.kreitz-webdev.de/docs/github-action): Run verbatra translate in GitHub Actions with the composite action: inputs, secret wiring, annotations, and the job summary. - [Human translation](https://verbatra.kreitz-webdev.de/docs/manual-translation): Export untranslated strings to an Excel workbook, hand it to a translator, and import the result back with the same safety checks as an automated run. - [Review translations in Studio](https://verbatra.kreitz-webdev.de/docs/review-in-studio): Start Verbatra Studio, work the needs-review queue, fix entries in place, and retranslate flagged keys from the local dashboard. - [Operate Studio with a browser agent](https://verbatra.kreitz-webdev.de/docs/agent-tools-in-studio): Expose Verbatra Studio's review actions as WebMCP tools so a browser AI agent can drive the same operations from your open, authenticated dashboard tab. ## CLI reference - [Overview](https://verbatra.kreitz-webdev.de/docs/cli): The verbatra command: its eight subcommands, the shared flags, how it reads your environment, and the exit-code contract. - [verbatra init](https://verbatra.kreitz-webdev.de/docs/cli/init): Create a verbatra config and .env example for this project. - [verbatra translate](https://verbatra.kreitz-webdev.de/docs/cli/translate): Translate every target locale once, then exit. - [verbatra watch](https://verbatra.kreitz-webdev.de/docs/cli/watch): Re-translate on every source change until interrupted. - [verbatra check](https://verbatra.kreitz-webdev.de/docs/cli/check): Report which keys are missing or stale per locale without writing files. - [verbatra diff](https://verbatra.kreitz-webdev.de/docs/cli/diff): Show the keys that would be added, re-translated, or orphaned per locale without writing files. - [verbatra export](https://verbatra.kreitz-webdev.de/docs/cli/export): Export untranslated strings into a styled Excel workbook for a human translator. - [verbatra import](https://verbatra.kreitz-webdev.de/docs/cli/import): Import a filled workbook back into the locale files, running the same safety checks. - [verbatra studio](https://verbatra.kreitz-webdev.de/docs/cli/studio): Start Verbatra Studio, the local translation dashboard. ## SDK - [SDK reference](https://verbatra.kreitz-webdev.de/docs/sdk): Every @verbatra/sdk entry point, grouped by job, with the error model and the RunSummary anatomy. - [SDK recipes](https://verbatra.kreitz-webdev.de/docs/programmatic-api): Complete, runnable patterns for driving verbatra from your own scripts, CI jobs, and tooling. ## Help - [FAQ](https://verbatra.kreitz-webdev.de/docs/faq): Short answers to the questions that come up most when running verbatra. - [Troubleshooting](https://verbatra.kreitz-webdev.de/docs/troubleshooting): Symptoms, causes, and fixes for the errors verbatra actually raises.