Docs / Primeiros passos / Início rápido
Página traduzida automaticamente
Início rápido com Flutter
Traduza os arquivos de locale ARB do seu app Flutter com o verbatra, da instalação à primeira string em alemão na tela.
Ao final desta página, seu app Flutter exibe uma string em alemão que o verbatra traduziu a partir de lib/l10n/app_, 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 Flutter 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.
Um app Flutter não tem package.json
Seu gerenciador de pacotes cria um na primeira instalação. Adicione node_ ao seu .gitignore.
Adicionar um arquivo de locale de origem
Pule este passo se lib/l10n/app_ já existir. Caso contrário, crie o arquivo com duas strings, uma delas com um placeholder:
{
"@@locale": "en",
"greeting": "Hello, {name}!",
"@greeting": {
"placeholders": { "name": { "type": "String" } }
},
"cartEmpty": "Your cart is empty."
}Gerar uma configuração
npx @verbatra/cli init --format arb --provider gemini --yes--format arb é o formato de arquivo de flutter_. O init encontra seus arquivos de locale ou grava o padrão lib/l10n/app_ 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 lib/l10n/app_. O texto depende do modelo, por exemplo:
{
"@@locale": "de",
"greeting": "Hallo, {name}!",
"cartEmpty": "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 flutter_:
flutter pub add flutter_localizations:"{sdk: flutter}" intl:anyDepois, carregue os dois arquivos e exiba a saudação:
flutter:
generate: truearb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dartimport 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';
void main() => runApp(
MaterialApp(
locale: const Locale('de'),
localizationsDelegates: AppLocalizations.localizationsDelegates,
supportedLocales: AppLocalizations.supportedLocales,
home: Builder(
builder: (context) => Text(AppLocalizations.of(context)!.greeting('Ada')),
),
),
);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.