---
title: "Verbatra: i18n CLI that translates only the changed keys"
description: "Verbatra is an open source i18n CLI and SDK. It finds missing and changed keys in your locale files and translates only those with your own provider key."
---

# 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](https://verbatra.kreitz-webdev.de/docs/quickstart.md)
- [Compare with other tools](https://verbatra.kreitz-webdev.de/compare)

```sh
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

[All formats](https://verbatra.kreitz-webdev.de/docs/formats.md)

### Providers

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

[All providers](https://verbatra.kreitz-webdev.de/docs/providers.md)

## The lock file

Two keys changed, two keys sent

- **Edit**: You change 2 values in your source file.
- **Compare**: Verbatra hashes every key and compares it with the lock file. 2 recorded hashes no longer match.
- **Send**: Only those 2 keys go to the provider. The other 12 are not sent.

**en.json** 2 changed

```json
{
  … 12 more, unchanged
  "checkout": {
    "title": "Review and checkout", changed
    "pay": "Pay and place order" changed
  }
}
```

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

```json
{
  "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.

**verbatra translate** 2 translated, 12 unchanged

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

**de.json** pre-generated, not live

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

gemini-2.5-flash, generated November 13, 2026
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](https://verbatra.kreitz-webdev.de/docs/translation-safety.md)

- **Candidate**: You changed profile.greeting in en.json. The provider returns a translation, and it lost {name}.
- **Refused**: The gate compares the candidate with the source and refuses it. The file is not touched.
- **Still stale**: The key stays stale, so the check still fails.

**profile.greeting** gemini-2.5-flash

**en.json** changed

```text
- "Welcome, {name}!"
+ "Welcome back, {name}!"
```

**de** provider answer

```text
"Willkommen zurück!" {name} missing
```

Nothing is checked or written yet.

**verbatra translate** not written 1 integrity-withheld

```text
$ 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

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

**verbatra check** exit 1

```text
$ 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

```json
"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

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

### CLI

```text
$ 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)
```

[docs/cli/check](https://verbatra.kreitz-webdev.de/docs/cli/check.md)

### Studio

| Locale | Coverage | Missing | Stale | Up to date |
| --- | --- | --- | --- | --- |
| de | 86% 12 / 14 keys | 0 | 2 | 12 |

[docs/cli/studio](https://verbatra.kreitz-webdev.de/docs/cli/studio.md)

### SDK

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

```sh
npm install --save-dev @verbatra/sdk
```

[docs/sdk/inspect](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md)

### MCP server

calls no provider

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

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

[docs/cli/mcp](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md)

## Features: Built for the whole translation workflow

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

### Extract from source

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

[`verbatra extract`](https://verbatra.kreitz-webdev.de/docs/cli/extract.md)

**verbatra extract** 2 new keys

```text
$ 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
```

### Typed keys

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

[`verbatra types`](https://verbatra.kreitz-webdev.de/docs/cli/types.md)

**verbatra-types.d.ts** 14 keys declared

```text
$ npx @verbatra/cli types
verbatra types
  14 keys declared, 1 of them taking arguments, from messages/en.json
  wrote verbatra-types.d.ts
```

```ts
export interface VerbatraMessages {
  … 8 more
  "profile.greeting": { readonly "name": VerbatraArgument };
  … 3 more
  "checkout.title": VerbatraNoArguments;
  "checkout.pay": VerbatraNoArguments;
}
```

### Know before you spend

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

[`verbatra doctor`](https://verbatra.kreitz-webdev.de/docs/cli/doctor.md)

**verbatra doctor** no API key needed

```text
$ 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)
```

### Watch while you build

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

[`verbatra watch`](https://verbatra.kreitz-webdev.de/docs/cli/watch.md)

**verbatra watch** on every save

```text
$ 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...
```

### Hand off to people

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

[`verbatra export`](https://verbatra.kreitz-webdev.de/docs/cli/export.md)

**verbatra-translations/de.csv** 2 rows to translate

```text
$ npx @verbatra/cli export --format csv
verbatra export -> verbatra-translations
  de: 2 rows
2 rows across 1 locale
```

| Key | Source | Status | Translation |
| --- | --- | --- | --- |
| checkout.pay | Pay and place order | changed | translator fills this in |
| checkout.title | Review and checkout | changed | translator fills this in |

### Review in Studio

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

[`verbatra studio`](https://verbatra.kreitz-webdev.de/docs/cli/studio.md)

**verbatra studio** real screenshot

## 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](https://github.com/verbatra/verbatra/blob/main/LICENSE), and you pay only your provider for the keys that changed; [estimating cost](https://verbatra.kreitz-webdev.de/docs/estimating-cost.md) 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](https://verbatra.kreitz-webdev.de/docs/providers.md) 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](https://verbatra.kreitz-webdev.de/docs/data-handling.md) 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](https://verbatra.kreitz-webdev.de/docs/github-action.md) 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](https://verbatra.kreitz-webdev.de/compare) checks it against other tools, with sources, including where they are stronger.

In the docs:

- [Quickstart](https://verbatra.kreitz-webdev.de/docs/quickstart.md)
- [Translation safety](https://verbatra.kreitz-webdev.de/docs/translation-safety.md)
- [Full comparison](https://verbatra.kreitz-webdev.de/compare)

## Start with a dry run

Before you spend a token

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

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

- [npm provenance](https://www.npmjs.com/package/@verbatra/cli)
- [MIT license](https://github.com/verbatra/verbatra/blob/main/LICENSE)
- [The CLI sends no telemetry](https://verbatra.kreitz-webdev.de/docs/data-handling.md)
- [90% coverage gate](https://codecov.io/gh/verbatra/verbatra)
- [CI workflow](https://github.com/verbatra/verbatra/actions/workflows/ci.yml)
