Docs / Primeiros passos / Início rápido
Página traduzida automaticamente
Início rápido com React
Traduza os arquivos de locale i18next do seu app React com o verbatra, da instalação até a primeira string em alemão na tela.
Ao final desta página, seu app React exibe uma string em alemão que o verbatra traduziu a partir de locales/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 React 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 locales/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 i18next-json --provider gemini --yes--format i18next-json é o formato de arquivo de react-i18next. O init encontra seus arquivos de locale ou grava o padrão locales/{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 locales/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 react-i18next:
npm install i18next react-i18nextDepois, carregue os dois arquivos e exiba a saudação:
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import de from "../locales/de.json";
import en from "../locales/en.json";
i18n.use(initReactI18next).init({
lng: "de",
fallbackLng: "en",
resources: { en: { translation: en }, de: { translation: de } },
});import { useTranslation } from "react-i18next";
export function Greeting() {
const { t } = useTranslation();
return <p>{t("greeting", { name: "Ada" })}</p>;
}import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { Greeting } from "./Greeting";
import "./i18n";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<Greeting />
</StrictMode>,
);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.