Skip to content
Skip to Content
verbatra

Documentation

Set up verbatra and keep every locale in sync.

Guides and reference for the CLI, the SDK, Studio, and the MCP server: start with the quickstart, or let your coding agent set verbatra up.

Start from your goal

Pick what you want to do; each card opens the page that does it.

Translate a projectInstall the CLI, preview the run without a key, then translate your first file.QuickstartGate pull requestsFail a pull request when a locale drifts, with JSON output for scripts.CI and exit codesHand off to translatorsExport a workbook for a person to translate, then import it back.Human translation

Pick your stack

A card marked Quickstart opens a step-by-step guide for that stack; every other card opens its init command and file layout.

Every run is a diff, not a rewrite.

What happens when you run verbatra translate.

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.

  1. 1. Check

    verbatra check compares the source, the targets and the lock file. It calls no provider and needs no key.

  2. 2. Translate

    verbatra translate sends only missing and changed keys, and refuses any result with mismatched placeholders, broken inline markup or invalid ICU syntax.

  3. 3. Gate in CI

    The GitHub Action runs check on each pull request and fails it while a locale is out of sync.

verbatra reads and writes the common locale file formats, from JSON and YAML to XLIFF, gettext, and Android and Apple catalogs, and translates through any supported LLM or machine-translation provider behind one interface (or none, for a human-only workflow), and a format it does not ship can be added as a custom adapter. The full lists are on Formats and Providers.

The packages

One engine, four ways to drive it.

@verbatra/cli0.13.6

The verbatra binary: every command, from init and extract to translate, check, export, and studio, as a thin wrapper over the SDK. Start here.

@verbatra/sdk0.13.6

The engine underneath: translate, watch, check, diff, doctor, extract, pseudolocalization, type generation, and the Excel and TMX round-trips, all from code.

@verbatra/studio0.7.7

A local dashboard with in-place editing, a review queue, an Overview of coverage and runs, and browser agent tools. Provider spend stays off unless you opt in.

@verbatra/mcp0.4.6

A stdio MCP server exposing translation status, glossary, and editing tools to Claude Code, Cursor, or any MCP client.