Docs / Primeiros passos / Início rápido
Página traduzida automaticamente
Início rápido com Angular
Traduza os arquivos de locale ngx-translate do seu app Angular com o verbatra, da instalação até a primeira string em alemão na tela.
Ao final desta página, seu app Angular exibe uma string em alemão que o verbatra traduziu a partir de src/assets/i18n/en.json, e um arquivo de lock faz com que cada execução seguinte traduza só o que mudou. Você precisa do Node.js ^22.22.0 || >=24, de um projeto Angular e de cerca de dez minutos. Os quatro primeiros passos não exigem conta nem chave de API.
Já tem arquivos de locale e um agente de programação? Em vez disso, entregue a ele o prompt de Configurar o verbatra com um agente de IA: ele se adapta aos arquivos que seu projeto já tem e para antes de gastar qualquer coisa.
Passos
Instalar a CLI
npm install --save-dev @verbatra/cliO verbatra é uma ferramenta de desenvolvimento e nunca vai junto com seu app. Os comandos abaixo usam npx; com pnpm, yarn ou bun, execute pnpm verbatra, yarn verbatra ou bun run verbatra.
Adicionar um arquivo de locale de origem
Pule este passo se src/assets/i18n/en.json já existir. Caso contrário, crie o arquivo com duas strings, uma delas com um placeholder:
{
"greeting": "Hello, {{name}}!",
"cart": {
"empty": "Your cart is empty."
}
}Gerar uma configuração
npx @verbatra/cli init --format ngx-translate-json --provider gemini --yes--format ngx-translate-json é o formato de arquivo de @ngx-translate/core. O init encontra seus arquivos de locale ou grava o padrão src/assets/i18n/{locale}.json quando ainda não há nenhum. --yes aceita o que o init detectou, sem perguntar. 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)Uma simulação não instancia nenhum provedor, então não exige chave de API, não gasta nada e não grava nada.
Traduzir
cp .env.example .envAbra o .env e cole sua chave de API depois de GEMINI_. Ainda não tem uma chave de API? O Gemini tem um nível gratuito: crie uma no Google AI Studio. Cada um dos outros provedores e sua variável estão em Provedores.
npx @verbatra/cli translateO verbatra envia as duas strings ao Gemini, confere se todos os placeholders sobreviveram e grava src/assets/i18n/de.json. O texto 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 código 1 assim que um locale sai de sincronia, então pode barrar um pull request.
Carregar os locales no seu app
Adicione @ngx-translate/core:
npm install @ngx-translate/core @ngx-translate/http-loaderDepois, carregue os dois arquivos e exiba a saudação:
import { provideHttpClient } from "@angular/common/http";
import type { ApplicationConfig } from "@angular/core";
import { provideTranslateService } from "@ngx-translate/core";
import { provideTranslateHttpLoader } from "@ngx-translate/http-loader";
export const appConfig: ApplicationConfig = {
providers: [
// keep the providers the Angular CLI generated, and add:
provideHttpClient(),
provideTranslateService({
lang: "de",
fallbackLang: "en",
loader: provideTranslateHttpLoader({ prefix: "./assets/i18n/", suffix: ".json" }),
}),
],
};import { Component } from "@angular/core";
import { TranslatePipe } from "@ngx-translate/core";
@Component({
selector: "app-root",
imports: [TranslatePipe],
template: `<p>{{ 'greeting' | translate: { name: 'Ada' } }}</p>`,
})
export class App {}// projects.<name>.architect.build.options
"assets": [
{ "glob": "**/*", "input": "public" },
{ "glob": "**/*", "input": "src/assets", "output": "assets" }
]Inicie seu app: a saudação aparece como Hallo, Ada!.
O que acabou de acontecer
- O
verbatra.lock.jsonregistra um hash de cada string de origem, então a próxima execução envia só as strings novas e alteradas. Veja O arquivo de lock e a procedência. - Um resultado que perde um placeholder fica retido e nunca é gravado. Veja Segurança da tradução.
Faça commit dos arquivos de locale, do verbatra.lock.json e do verbatra.provenance.json juntos.
Opcional: conectar seu agente de programação
npx @verbatra/cli init --agentCom a configuração já existente, o init --agent a mantém e adiciona só os arquivos de agente: as regras do verbatra em AGENTS.md (ou em CLAUDE.md, quando esse é seu único arquivo de instruções) e o servidor MCP do verbatra, com os gastos desativados, na configuração de projeto de cada agente de programação que ele detecta. Quais arquivos ele grava para cada agente, e como usar --client para nomear os agentes você mesmo, estão em Configurar agentes de programação. --dry-run mostra os arquivos sem gravá-los.
Ou, sem a CLI, adicione só o servidor MCP ao seu perfil de usuário do VS Code; use um caminho só, nunca os dois:
Próximos passos
Adicionar um idioma
Adicione um locale de destino e deixe uma execução preenchê-lo.
Executar o verbatra na CI
Faça um pull request falhar quando um locale divergir.
Escolher sua stack
O id do formato e a estrutura de arquivos de cada outro framework.