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)O arquivo de lock
en.json 2 alteradas
{
… mais 12, inalteradas
"checkout": {
"title": "Review and checkout", alterada
"pay": "Pay and place order" alterada
}
}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.
verbatra translate 2 translated, 12 unchanged
$ npx @verbatra/cli translate
de: 2 translated, 12 unchangedde.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
Todo candidato passa por uma barreira de integridade antes de chegar ao seu arquivo. docs/translation-safety
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} ausenteNada foi verificado nem gravado ainda.
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 failedde.json inalterado
"profile": {
"greeting": "Willkommen, {name}!",
...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
Da primeira string no seu código-fonte até a tradução revisada em produção.
verbatra extractverbatra 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 writtenwould 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/extractverbatra typesverbatra-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.tsexport 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/typesverbatra doctorverbatra 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/doctorverbatra watchverbatra 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/watchverbatra exportverbatra-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| 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 |
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/exportverbatra studioverbatra 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/studioO resultado
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$ 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)| Locale | Coverage | Missing | Stale | Up to date |
|---|---|---|---|---|
| de | 93% 13 / 14 keys | 0 | 1 | 13 |
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
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
O que decide um fluxo de tradução, respondido para as ferramentas que as equipes mais avaliam.
| Pergunta | 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
As perguntas
Respostas curtas, cada uma com a página da documentação que aprofunda o assunto.
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.
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.
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.
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.
É 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
Este caminho é para um projeto que já tem arquivos de locale, e nenhuma das duas etapas precisa de chave de API.
npx @verbatra/cli initnpx @verbatra/cli translate --dry-run