Pular para o conteúdo

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

Provedores

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

O arquivo de lock

Duas chaves alteradas, duas chaves enviadas

EditarVocê altera 2 valores no seu arquivo de origem.

en.json 2 alteradas

{
… mais 12, inalteradas
"checkout": {
"title": "Review and checkout", alterada
"pay": "Pay and place order" alterada
}
}
CompararO Verbatra gera o hash de cada chave e o compara com o arquivo de lock. 2 hashes registrados não batem mais.

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

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

EnviarSó 2 chaves vão para o provedor. As outras 12 não são enviadas.

verbatra translate 2 translated, 12 unchanged

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

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

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

gemini-2.5-flash,
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

CandidatoVocê alterou profile.greeting em en.json. O provedor devolve uma tradução, e ela perdeu {name}.

profile.greeting gemini-2.5-flash

en.json alterado

"Welcome back, {name}!"
"Good to see you, {name}!"

de resposta do provedor

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

Nada foi verificado nem gravado ainda.

RecusadoA barreira compara o candidato com a origem e o recusa. O arquivo não é tocado.

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

"profile": {
"greeting": "Willkommen, {name}!",
...
Continua obsoletaA chave continua obsoleta, então a verificação continua falhando.

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 inalterado

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

  1. verbatra extract

    verbatra extract 2 novas chaves

    $ 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

    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.

    docs/cli/extract
  2. verbatra types

    verbatra-types.d.ts 14 chaves declaradas

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

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

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

    docs/cli/types
  3. verbatra doctor

    verbatra doctor sem chave de API

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

    de: 2 would translate, 12 unchanged

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

    docs/cli/doctor
  4. verbatra watch

    verbatra watch a cada salvamento

    $ 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

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

    docs/cli/watch
  5. verbatra export

    verbatra-translations/de.csv 2 linhas para traduzir

    $ npx @verbatra/cli export --format csv
    verbatra export -> verbatra-translations
      de: 2 rows
    2 rows across 1 locale
    KeySourceStatusTranslation
    checkout.payPay and place orderchangedo tradutor preenche aqui
    checkout.titleReview and checkoutchangedo tradutor preenche aqui

    de: 2 rows

    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.

    docs/cli/export
  6. verbatra studio

    verbatra studio captura de tela real

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

    docs/cli/studio

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

"profile.greeting": "deb45ffcf3548530", stale

CLI

verbatra check
$ 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)

Studio

Locales
Cobertura de locales
LocaleCoverageMissingStaleUp to date
de93% 13 / 14 keys0113

SDK

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

npm install --save-dev @verbatra/sdk

Servidor MCP

não chama nenhum provedor
status.check({})
{ "inSync": false, "locales": [
  { "locale": "de", "missing": 0,
    "stale": 1, "upToDate": 13, ... }
] }

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

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
PerguntaVerbatraCrowdinTolgeeLingo.devFluxo manual
Funciona sem conta de fornecedorSimNãoParcialNãoSim
Suas próprias chaves de provedorSimSimParcialParcialSim
Traduz só as chaves alteradasSimParcialParcialSimNão
A CI falha com traduções ausentes ou obsoletasSimSimNãoSimNão
Verifica placeholders e ICU após traduzirSimSimSimParcialNão
Editor web para tradutoresParcialSimSimParcialNão

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

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 (abre em uma nova aba), e você paga só ao seu provedor pelas chaves alteradas; a estimativa de custo 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 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 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 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 a confronta com outras ferramentas, inclusive onde são mais fortes.

Antes de gastar um token

Comece com uma simulação

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

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