Docs / Primeiros passos / Início rápido
Página traduzida automaticamente
Início rápido com Next.js
Traduza os arquivos de locale next-intl do seu app Next.js com o verbatra, da instalação até a primeira string em alemão na tela.
Ao final desta página, seu app Next.js exibe uma string em alemão que o verbatra traduziu a partir de messages/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 Next.js 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 messages/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 next-intl-json --provider gemini --yes--format next-intl-json é o formato de arquivo de next-intl. O init encontra seus arquivos de locale ou grava o padrão messages/{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 messages/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 next-intl:
npm install next-intlDepois, carregue os dois arquivos e exiba a saudação:
import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";
const nextConfig: NextConfig = {};
export default createNextIntlPlugin()(nextConfig);// with a src/ folder: src/i18n/request.ts, importing ../../messages
import { getRequestConfig } from "next-intl/server";
export default getRequestConfig(async () => {
const locale = "de";
return {
locale,
messages: (await import(`../messages/${locale}.json`)).default,
};
});import { useTranslations } from "next-intl";
export default function Home() {
const t = useTranslations();
return <p>{t("greeting", { name: "Ada" })}</p>;
}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.