---
title: "Verbatra: CLI de i18n que traduz só as chaves alteradas"
description: "Verbatra é uma CLI e um SDK de i18n de código aberto. Ele encontra chaves ausentes e alteradas nos arquivos de locale e traduz só essas, com sua chave de API."
---

# Traduza só o que mudou

O Verbatra gera o hash de cada chave em um arquivo de lock, envia só as chaves alteradas ao seu provedor e faz a CI falhar quando há divergência.

- [Começar](https://verbatra.kreitz-webdev.de/pt-BR/docs/quickstart.md)
- [Comparar com outras ferramentas](https://verbatra.kreitz-webdev.de/pt-BR#compare)

```sh
npm i -D @verbatra/cli
```

## Funciona com os arquivos de locale e os provedores que você já usa

### Formatos de arquivo

- 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

[Todos os formatos](https://verbatra.kreitz-webdev.de/pt-BR/docs/formats.md)

### Provedores

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

[Todos os provedores](https://verbatra.kreitz-webdev.de/pt-BR/docs/providers.md)

## O arquivo de lock

Duas chaves alteradas, duas chaves enviadas

- **Editar**: Você altera 2 valores no seu arquivo de origem.
- **Comparar**: O Verbatra gera o hash de cada chave e o compara com o arquivo de lock. 2 hashes registrados não batem mais.
- **Enviar**: Só 2 chaves vão para o provedor. As outras 12 não são enviadas.

**en.json** 2 alteradas

```json
{
  … mais 12, inalteradas
  "checkout": {
    "title": "Review and checkout", alterada
    "pay": "Pay and place order" alterada
  }
}
```

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

```json
{
  "version": 1,
  "locales": {
    "de": {
      … mais 4, inalteradas
      "cart.total": "692deda3edfe75da",
      "checkout.pay": "bcdca4b40874a53a", obsoleta
      "checkout.title": "f0eeada9213af138", obsoleta
      "errors.notFound": "427078dedd81b2ce",
      … mais 6, inalteradas
    }
  }
}
```

Obsoleta (stale) significa que o hash registrado difere do hash do valor atual de en.json. As outras 12 batem.

**verbatra translate** 2 translated, 12 unchanged

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

**de.json** pré-gerado, não ao vivo

```json
{
  … mais 12, inalteradas
  "checkout": {
    "title": "Überprüfen und zur Kasse gehen", alterada
    "pay": "Bezahlen und Bestellung aufgeben" alterada
  }
}
```

gemini-2.5-flash, gerado em 13 de novembro de 2026
verbatra.lock.json: 2 hashes atualizados.

## A barreira: Quando o provedor erra, nada é gravado

Todo candidato passa por uma barreira de integridade antes de chegar ao seu arquivo. [docs/translation-safety](https://verbatra.kreitz-webdev.de/pt-BR/docs/translation-safety.md)

- **Candidato**: Você alterou profile.greeting em en.json. O provedor devolve uma tradução, e ela perdeu {name}.
- **Recusado**: A barreira compara o candidato com a origem e o recusa. O arquivo não é tocado.
- **Continua obsoleta**: A chave continua obsoleta, então a verificação continua falhando.

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

**en.json** alterado

```text
- "Welcome back, {name}!"
+ "Good to see you, {name}!"
```

**de** resposta do provedor

```text
"Schön, Sie zu sehen!" {name} ausente
```

Nada foi verificado nem gravado ainda.

**verbatra translate** não gravado 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** inalterado

```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** inalterado

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

de.json mantém o valor anterior. A chave continua obsoleta e é tentada de novo na próxima execução.

Um arquivo de lock. Todo comando o lê.

## Os comandos: Feito para todo o fluxo de tradução

Da primeira string no seu código-fonte até a tradução revisada em produção.

### Extrair do código-fonte

Varra seu código atrás de chamadas de tradução e adicione as novas chaves ao locale de origem antes que alguém traduza.

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

**verbatra extract** 2 novas chaves

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

### Chaves tipadas

Gere declarações TypeScript para suas chaves e argumentos de mensagem, para que um erro de digitação em uma chave quebre o build.

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

**verbatra-types.d.ts** 14 chaves declaradas

```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 {
  … mais 8
  "profile.greeting": { readonly "name": VerbatraArgument };
  … mais 3
  "checkout.title": VerbatraNoArguments;
  "checkout.pay": VerbatraNoArguments;
}
```

### Saiba antes de gastar

O doctor verifica a configuração sem chave de API, e uma estimativa dimensiona uma execução antes de ela custar qualquer coisa.

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

**verbatra doctor** sem chave de API

```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.
  … mais verificações, todas aprovadas
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)
```

### Observar enquanto você desenvolve

Mantenha o processo do watch em execução durante o desenvolvimento, e cada alteração no locale de origem é traduzida ao salvar.

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

**verbatra watch** a cada salvamento

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

### Entregar a pessoas

Exporte uma pasta de trabalho do Excel, CSV, TSV ou XLIFF para um tradutor e importe de volta. Os valores importados ficam protegidos de execuções automáticas posteriores.

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

**verbatra-translations/de.csv** 2 linhas para traduzir

```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 | o tradutor preenche aqui |
| checkout.title | Review and checkout | changed | o tradutor preenche aqui |

### Revisar no Studio

Um painel local sobre o seu projeto: navegue por todos os locales, trabalhe a fila de revisão e edite valores diretamente.

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

**verbatra studio** captura de tela real

## O resultado: Pergunte a qualquer interface, receba a mesma resposta

Toda interface lê o mesmo arquivo de lock, então com profile.greeting recusada, o alemão aparece com obsoletas: 1 e em dia: 13, onde quer que você pergunte.

**verbatra.lock.json** 1 stale, 13 up-to-date

```text
"profile.greeting": "deb45ffcf3548530", stale
```

### CLI

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

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

### Studio

| Locale | Coverage | Missing | Stale | Up to date |
| --- | --- | --- | --- | --- |
| de | 93% 13 / 14 keys | 0 | 1 | 13 |

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

### SDK

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

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

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

### Servidor MCP

não chama nenhum provedor

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

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

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

## As alternativas: Como o Verbatra se compara

O que decide um fluxo de tradução, respondido para as ferramentas que as equipes mais avaliam.

Como o Verbatra se compara com Crowdin, Tolgee, Lingo.dev e um fluxo manual

| | Verbatra | Crowdin | Tolgee | Lingo.dev | Fluxo manual |
| --- | --- | --- | --- | --- | --- |
| Funciona sem conta de fornecedor | Sim | Não | Parcial | Não | Sim |
| Suas próprias chaves de provedor | Sim | Sim | Parcial | Parcial | Sim |
| Traduz só as chaves alteradas | Sim | Parcial | Parcial | Sim | Não |
| A CI falha com traduções ausentes ou obsoletas | Sim | Sim | Não | Sim | Não |
| Verifica placeholders e ICU após traduzir | Sim | Sim | Sim | Parcial | Não |
| Editor web para tradutores | Parcial | Sim | Sim | Parcial | Não |

Última verificação em 16 de novembro de 2026

Fontes:

- **Funciona sem conta de fornecedor**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/config/provider-config.ts> <https://github.com/verbatra/verbatra/blob/main/packages/ai-providers/src/env.ts>
  - Crowdin: <https://crowdin.github.io/crowdin-cli/> <https://github.com/crowdin/crowdin-cli>
  - Tolgee: <https://docs.tolgee.io/tolgee-cli/usage> <https://docs.tolgee.io/platform/self_hosting/licensing>
  - Lingo.dev: <https://lingo.dev/en/docs/cli>
- **Suas próprias chaves de provedor**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/ai-providers/src/env.ts>
  - Crowdin: <https://support.crowdin.com/crowdin-ai/> <https://support.crowdin.com/machine-translation/>
  - Tolgee: <https://docs.tolgee.io/platform/projects_and_organizations/llm-providers> <https://docs.tolgee.io/platform/translation_process/machine_translation>
  - Lingo.dev: <https://lingo.dev/pricing> <https://lingo.dev/en/docs/platform/llm-models>
- **Traduz só as chaves alteradas**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/flow/locale-run.ts>
  - Crowdin: <https://support.crowdin.com/pre-translation/>
  - Tolgee: <https://docs.tolgee.io/platform/projects_and_organizations/machine-translation-settings>
  - Lingo.dev: <https://lingo.dev/en/docs/cli/ci>
- **A CI falha com traduções ausentes ou obsoletas**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/cli/src/run.ts>
  - Crowdin: <https://crowdin.github.io/crowdin-cli/commands/crowdin-status>
  - Tolgee: <https://github.com/tolgee/tolgee-cli/tree/main/src/commands> <https://raw.githubusercontent.com/tolgee/tolgee-cli/main/src/commands/sync/compare.ts>
  - Lingo.dev: <https://lingo.dev/en/docs/cli/ci>
- **Verifica placeholders e ICU após traduzir**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/core/src/placeholder/integrity.ts> <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/flow/integrity-gate.ts>
  - Crowdin: <https://support.crowdin.com/project-settings/qa-checks/>
  - Tolgee: <https://docs.tolgee.io/platform/translation_process/qa_checks>
  - Lingo.dev: <https://lingo.dev/en/docs/platform/ai-reviewers>
- **Editor web para tradutores**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/studio/src/server/create-studio-server.ts>
  - Crowdin: <https://support.crowdin.com/online-editor/>
  - Tolgee: <https://docs.tolgee.io/platform/>
  - Lingo.dev: <https://lingo.dev/en/docs/api/pipeline/human-review>

## As perguntas: Antes de instalar o Verbatra

Respostas curtas, cada uma com a página da documentação que aprofunda o assunto.

### O Verbatra é gratuito?

Sim. É gratuito e de código aberto sob a [licença MIT](https://github.com/verbatra/verbatra/blob/main/LICENSE), e você paga só ao seu provedor pelas chaves alteradas; a [estimativa de custo](https://verbatra.kreitz-webdev.de/pt-BR/docs/estimating-cost.md) dimensiona uma execução antes.

### Quais provedores de tradução o Verbatra aceita?

Anthropic, OpenAI, Gemini, DeepL, Google Cloud Translation, OpenCode, OpenAI-compatible e LibreTranslate. Defina um em `provider`, ou `none` quando só pessoas traduzem; a [página de provedores](https://verbatra.kreitz-webdev.de/pt-BR/docs/providers.md) detalha cada um.

### O Verbatra envia minhas strings ou chaves de API para algum lugar?

Só ao provedor configurado, quando um comando traduz; não há telemetria. As chaves de API ficam em variáveis de ambiente; [tratamento de dados](https://verbatra.kreitz-webdev.de/pt-BR/docs/data-handling.md) lista o que cada provedor recebe.

### O Verbatra pode reprovar um pull request quando faltam traduções?

Sim. `verbatra check` sai com 1 enquanto um locale tem chaves ausentes ou obsoletas, sem precisar de chave de API; a [GitHub Action](https://verbatra.kreitz-webdev.de/pt-BR/docs/github-action.md) o executa em pull requests.

### Em que o Verbatra difere de outras ferramentas de i18n?

É uma CLI que usa seus próprios arquivos versionados, não uma plataforma hospedada. A [tabela de comparação](https://verbatra.kreitz-webdev.de/pt-BR#compare) a confronta com outras ferramentas, inclusive onde são mais fortes.

Na documentação:

- [Início rápido](https://verbatra.kreitz-webdev.de/pt-BR/docs/quickstart.md)
- [Segurança da tradução](https://verbatra.kreitz-webdev.de/pt-BR/docs/translation-safety.md)
- [Tabela comparativa](https://verbatra.kreitz-webdev.de/pt-BR#compare)

## Comece com uma simulação

Antes de gastar um token

Este caminho é para um projeto que já tem arquivos de locale, e nenhuma das duas etapas precisa de chave de API.

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

- [Atestado de procedência do npm](https://www.npmjs.com/package/@verbatra/cli)
- [Licença MIT](https://github.com/verbatra/verbatra/blob/main/LICENSE)
- [A CLI não envia telemetria](https://verbatra.kreitz-webdev.de/pt-BR/docs/data-handling.md)
- [Barreira de cobertura de 90%](https://codecov.io/gh/verbatra/verbatra)
- [Fluxo de trabalho de CI](https://github.com/verbatra/verbatra/actions/workflows/ci.yml)
