Docs / Primeiros passos
Página traduzida automaticamente
Início rápido
Instale a CLI, gere uma configuração, pré-visualize a execução sem chave de API e traduza seu primeiro arquivo de locale.
Ao fim desta página, um arquivo de locale em inglês terá um irmão em alemão, escrito por um provedor e verificado pelo verbatra, além do arquivo de lock que faz toda execução seguinte traduzir só o que mudou. Você precisa do Node.js ^22.22.0 || >=24 e de cerca de 10 minutos. Os quatro primeiros passos não exigem conta nem chave de API.
Já tem arquivos de locale e um agente de programação?
Passe ao seu agente o prompt de Configurar o verbatra com um agente de IA. Ele adiciona o verbatra em torno dos arquivos de locale que o seu projeto já tem e para antes de gastar qualquer coisa. Os passos abaixo partem do zero.
Existe um início rápido que também carrega o arquivo traduzido no seu app para React, Next.js, Vue, Angular e Flutter.
Passos
Instalar a CLI
npm install --save-dev @verbatra/cliOs comandos abaixo usam npx. Com pnpm, yarn ou bun, execute pnpm verbatra, yarn verbatra ou bun run verbatra em vez disso. Se o pnpm terminar com ERR_, veja O pnpm bloqueia os scripts de instalação de uma dependência (ERR_PNPM_IGNORED_BUILDS).
Adicionar um arquivo de locale de origem
Pule este passo se o seu projeto já tem arquivos de locale. Caso contrário, crie um:
{
"greeting": "Hello, {{name}}!",
"cart": {
"empty": "Your cart is empty."
}
}Gerar uma configuração
npx @verbatra/cli init --format i18next-json --provider gemini --yes--format nomeia o formato do seu arquivo: Escolher sua stack traz o id de cada framework. --yes aceita o que o init detectou em vez de perguntar; omita-o para responder às perguntas interativas que o verbatra init lista.
created verbatra.config.ts
created .env.example
created .gitignore (.env, .env.local, .verbatra-local/, verbatra.cache.json)
detected format i18next-json, pattern locales/{locale}.json, locales en (confidence: medium)
next steps:
- Copy .env.example to .env and set GEMINI_API_KEY there. Never commit .env.
- npx @verbatra/cli doctor (Check the setup. It calls no provider and reads no key value.)
- npx @verbatra/cli translate --dry-run (Preview what a run would translate, without calling the provider.)O novo verbatra.config.ts traduz de en para de. Adicione códigos a targetLocales para ter mais idiomas.
Pré-visualizar a execução sem chave de API
npx @verbatra/cli translate --dry-runverbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)Esta é a forma no terminal interativo; em um pipe ou na CI, cada etapa também recebe uma linha própria, veja Saída no terminal. Uma simulação não instancia nenhum provedor, então não precisa de chave de API, não gasta nada e não grava nada. O verbatra doctor verifica o restante da configuração do mesmo modo.
Traduzir
cp .env.example .envAbra o .env e cole sua chave de API depois de GEMINI_. As chaves de API só vêm do ambiente, e a CLI carrega .env.local e .env nele. Ainda sem chave de API? O Gemini tem um nível gratuito: crie uma no Google AI Studio. Todos os outros provedores e suas variáveis estão em Provedores.
npx @verbatra/cli translateO verbatra envia as duas chaves ausentes ao Gemini, verifica cada resultado e grava o arquivo em alemão. O resumo começa com de: 2 translated, 0 unchanged e lista os tokens que a execução usou. A redação depende do modelo, por exemplo:
{
"greeting": "Hallo, {{name}}!",
"cart": {
"empty": "Dein Warenkorb ist leer."
}
}Verificar se todos os locales estão sincronizados
npx @verbatra/cli check[ok] checking the locales (0.0s)
verbatra check
de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in syncO check não chama nenhum provedor e termina com 1 assim que um locale sai de sincronia, então o mesmo comando pode barrar um pull request.
O que acabou de acontecer
locales/de.jsoncontém as mesmas chaves, na mesma ordem da sua origem, e{{name}}sobreviveu: um resultado que perde um placeholder fica retido e nunca é gravado. Veja Segurança da tradução.verbatra.lock.jsonregistra um hash da string de origem por trás de cada tradução, então a próxima execução envia só as chaves novas e alteradas. Veja O arquivo de lock e a procedência.verbatra.provenance.jsonregistra qual provedor e qual modelo escreveram cada valor. Veja Procedência: quem escreveu cada valor.verbatra.cache.jsone.verbatra-local/guardam o cache de tradução, que pode ser regenerado, e o estado local das execuções. Oinitjá colocou os dois no gitignore. Veja O cache de tradução.
Faça commit dos arquivos de locale, do arquivo de lock e do arquivo de procedência juntos, para que todas as máquinas e a sua CI comparem com a mesma linha de base.
Próximos passos
Adicionar um idioma
Adicione um locale de destino e deixe uma execução preenchê-lo.
Executar o verbatra na CI
Reprove um pull request quando um locale divergir.
Como funciona uma execução
O fluxo por trás dos comandos que você acabou de executar.
Arquivo de configuração
Tudo o que o verbatra.config.ts pode conter.