Skip to content

Translate only what changed

Verbatra hashes every key in a lock file, sends only changed keys to your provider, and fails CI on drift.

Get started
npm i -D @verbatra/cli

Works with the locale files and providers you already use

File formats

  • i18next JSON
  • vue-i18n JSON
  • next-intl JSON
  • ngx-translate JSON
  • XLIFF
  • YAML
  • Flutter ARB
  • Java/Spring .properties
  • Apple .strings
  • Xcode String Catalog
  • Android strings.xml
  • gettext .po/.pot
  • INI
  • .NET .resx

Providers

  • Anthropic
  • OpenAI
  • Gemini
  • DeepL
  • Google Cloud Translation
  • OpenCode
  • OpenAI-compatible
  • LibreTranslate

The lock file

Two keys changed, two keys sent

EditYou change 2 values in your source file.

en.json 2 changed

{
… 12 more, unchanged
"checkout": {
"title": "Review and checkout", changed
"pay": "Pay and place order" changed
}
}
CompareVerbatra hashes every key and compares it with the lock file. 2 recorded hashes no longer match.

verbatra.lock.json 2 stale, 12 up-to-date

{
"version": 1,
"locales": {
"de": {
… 4 more, unchanged
"cart.total": "692deda3edfe75da",
"checkout.pay": "bcdca4b40874a53a", stale
"checkout.title": "f0eeada9213af138", stale
"errors.notFound": "427078dedd81b2ce",
… 6 more, unchanged
}
}
}

Stale means the recorded hash differs from the hash of the current en.json value. The other 12 match.

SendOnly those 2 keys go to the provider. The other 12 are not sent.

verbatra translate 2 translated, 12 unchanged

$ npx @verbatra/cli translate
  de: 2 translated, 12 unchanged

de.json pre-generated, not live

{
… 12 more, unchanged
"checkout": {
"title": "Überprüfen und zur Kasse gehen", changed
"pay": "Bezahlen und Bestellung aufgeben" changed
}
}

gemini-2.5-flash,
verbatra.lock.json: 2 hashes updated.

When the provider gets it wrong, nothing is written

Every candidate passes an integrity gate before it reaches your file. docs/translation-safety

CandidateYou changed profile.greeting in en.json. The provider returns a translation, and it lost {name}.

profile.greeting gemini-2.5-flash

en.json changed

"Welcome, {name}!"
"Welcome back, {name}!"

de provider answer

"Willkommen zurück!" {name} missing

Nothing is checked or written yet.

RefusedThe gate compares the candidate with the source and refuses it. The file is not touched.

verbatra translate not written 1 integrity-withheld

$ npx @verbatra/cli translate
  de: failed, 0 translated, 13 unchanged, 1 integrity-withheld
    integrity-withheld:
      profile.greeting: placeholder (-{name})
0 succeeded, 0 partial, 1 failed

de.json unchanged

"profile": {
"greeting": "Willkommen, {name}!",
...
Still staleThe key stays stale, so the check still fails.

verbatra check exit 1

$ npx @verbatra/cli check
  de: 0 missing, 1 stale, 13 up-to-date (out of sync)
out of sync (run verbatra translate to update)

de.json unchanged

"profile": {
"greeting": "Willkommen, {name}!",
...

de.json keeps the previous value. The key stays stale and is retried next run.

Ask any surface, get the same answer

Every surface reads one lock file, so German reads 2 stale and 12 up-to-date wherever you ask.

verbatra.lock.json 2 stale, 12 up-to-date

"checkout.pay": "bcdca4b40874a53a", stale
"checkout.title": "f0eeada9213af138", stale

CLI

verbatra check
$ npx @verbatra/cli check
verbatra check
  de: 0 missing, 2 stale, 12 up-to-date (out of sync)
out of sync (run verbatra translate to update)

Studio

Locales
Locale coverage
LocaleCoverageMissingStaleUp to date
de86% 12 / 14 keys0212

SDK

check()
import { check } from "@verbatra/sdk";
const summary = await check({ config });
summary.locales[0];
// { locale: "de", missing: 0,
//   stale: 2, upToDate: 12,
//   inSync: false, ... }

npm install --save-dev @verbatra/sdk

MCP server

calls no provider
status.check({})
{ "inSync": false, "locales": [
  { "locale": "de", "missing": 0,
    "stale": 2, "upToDate": 12, ... }
] }

claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp

Features

Built for the whole translation workflow

From the first string in your source code to the reviewed translation in production.

  1. verbatra extract

    verbatra extract 2 new keys

    $ npx @verbatra/cli extract --dry-run
    verbatra extract
      1 file scanned, 2 keys already present
      would add 2 keys to messages/en.json
      new keys (2):
        checkout.giftNote  src/Checkout.tsx:8
        checkout.backToCart  src/Checkout.tsx:10
    dry run, nothing written

    would add 2 keys to messages/en.json

    Scan your code for translation calls and add the new keys to the source locale before anyone translates them.

    docs/cli/extract
  2. verbatra types

    verbatra-types.d.ts 14 keys declared

    $ npx @verbatra/cli types
    verbatra types
      14 keys declared, 1 of them taking arguments, from messages/en.json
      wrote verbatra-types.d.ts
    export interface VerbatraMessages {
      … 8 more
      "profile.greeting": { readonly "name": VerbatraArgument };
      … 3 more
      "checkout.title": VerbatraNoArguments;
      "checkout.pay": VerbatraNoArguments;
    }

    14 keys declared, 1 of them taking arguments, from messages/en.json

    Generate TypeScript declarations for your keys and message arguments, so a typo in a key fails the build.

    docs/cli/types
  3. verbatra doctor

    verbatra doctor no API key needed

    $ npx @verbatra/cli doctor
    verbatra doctor
      [ok  ] Configuration: Loaded .verbatrarc.json.
      [ok  ] Format adapter: Format "next-intl-json" resolves to an adapter.
      [ok  ] Provider: Provider "gemini" resolves to a factory.
      [fail] API key environment variable: The GEMINI_API_KEY environment variable is not set.
             fix: Set GEMINI_API_KEY in the environment, or, with the CLI, in a .env file in the project directory.
      … more checks, all passed
    1 problem found (run verbatra doctor again after fixing it)
    $ npx @verbatra/cli translate --dry-run
    verbatra translate (dry run)
      de: 2 would translate, 12 unchanged
    1 succeeded, 0 partial, 0 failed (dry run: nothing written)

    de: 2 would translate, 12 unchanged

    Doctor checks the setup without an API key, and an estimate sizes a run before it costs anything.

    docs/cli/doctor
  4. verbatra watch

    verbatra watch on every save

    $ npx @verbatra/cli watch
    verbatra: watching en (messages/{locale}.json); running initial translation
    verbatra: translating de
    verbatra: de batch 1/1
    verbatra: de: writing
    verbatra: de done, 2 translated
    verbatra: run finished, 1 locale processed
    verbatra translate
      de: 2 translated, 12 unchanged
    1 succeeded, 0 partial, 0 failed
    verbatra: waiting for changes...

    de: 2 translated, 12 unchanged

    Keep a watcher running in development, and every change to the source locale is translated as you save.

    docs/cli/watch
  5. verbatra export

    verbatra-translations/de.csv 2 rows to translate

    $ npx @verbatra/cli export --format csv
    verbatra export -> verbatra-translations
      de: 2 rows
    2 rows across 1 locale
    KeySourceStatusTranslation
    checkout.payPay and place orderchangedtranslator fills this in
    checkout.titleReview and checkoutchangedtranslator fills this in

    de: 2 rows

    Export an Excel workbook, CSV, TSV or XLIFF for a translator and import it back. Imported values stay protected from later machine runs.

    docs/cli/export
  6. verbatra studio

    verbatra studio real screenshot

    A local dashboard over your project: browse every locale, work through the review queue and edit values in place.

    docs/cli/studio

Before you install Verbatra

Short answers, each with the docs page that goes deeper.

Is Verbatra free?

Yes. Verbatra is free and open source under the MIT license (opens in a new tab), and you pay only your provider for the keys that changed; estimating cost sizes a run first.

Which translation providers does Verbatra support?

Anthropic, OpenAI, Gemini, DeepL, Google Cloud Translation, OpenCode, OpenAI-compatible, and LibreTranslate. Set one in provider, or none when only people translate; the providers page covers each.

Does Verbatra send my strings or API keys anywhere?

Only to the provider you configure, when a command translates; there is no telemetry. Keys stay in environment variables, and data handling lists what each provider receives.

Can Verbatra fail a pull request when translations are missing?

Yes. verbatra check exits 1 while a locale has missing or stale keys, with no API key needed; the GitHub Action runs it on pull requests.

How is Verbatra different from other i18n tools?

It is a CLI that runs on your own committed files, not a hosted platform. The comparison page checks it against other tools, with sources, including where they are stronger.

Before you spend a token

Start with a dry run

This path is for a project that already has locale files, and neither step needs an API key.

npx @verbatra/cli init
npx @verbatra/cli translate --dry-run