---
title: "Início rápido com Flutter"
description: "Traduza os arquivos de locale ARB do seu app Flutter com o verbatra, da instalação à primeira string em alemão na tela."
type: "tutorial"
---
# 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_en.arb`, 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](https://verbatra.kreitz-webdev.de/pt-BR/docs/start-with-ai.md): ele se adapta aos arquivos que seu projeto já tem e para antes de gastar qualquer coisa.

## Passos [#passos]

<Steps>
<Step>

### Instalar a CLI [#instalar-a-cli]

```bash
npm install --save-dev @verbatra/cli
```

O 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`.

<Callout title="Um app Flutter não tem package.json">
Seu gerenciador de pacotes cria um na primeira instalação. Adicione `node_modules/` ao seu `.gitignore`.
</Callout>

</Step>
<Step>

### Adicionar um arquivo de locale de origem [#adicionar-um-arquivo-de-locale-de-origem]

Pule este passo se `lib/l10n/app_en.arb` já existir. Caso contrário, crie o arquivo com duas strings, uma delas com um placeholder:

```json title="lib/l10n/app_en.arb"
{
  "@@locale": "en",
  "greeting": "Hello, {name}!",
  "@greeting": {
    "placeholders": { "name": { "type": "String" } }
  },
  "cartEmpty": "Your cart is empty."
}
```

</Step>
<Step>

### Gerar uma configuração [#gerar-uma-configuração]

```bash
npx @verbatra/cli init --format arb --provider gemini --yes
```

`--format` `arb` é o formato de arquivo de `flutter_localizations`. O `init` encontra seus arquivos de locale ou grava o padrão `lib/l10n/app_{locale}.arb` 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.

</Step>
<Step>

### Pré-visualizar a execução sem chave de API [#pré-visualizar-a-execução-sem-chave-de-api]

```bash
npx @verbatra/cli translate --dry-run
```

```text output
verbatra: 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.

</Step>
<Step>

### Traduzir [#traduzir]

```bash
cp .env.example .env
```

Abra o `.env` e cole sua chave de API depois de `GEMINI_API_KEY=`. Ainda não tem uma chave de API? O Gemini tem um nível gratuito: crie uma no [Google AI Studio](https://aistudio.google.com/apikey). Cada um dos outros provedores e sua variável estão em [Provedores](https://verbatra.kreitz-webdev.de/pt-BR/docs/providers.md).

```bash
npx @verbatra/cli translate
```

O verbatra envia as duas strings ao Gemini, confere se todos os placeholders sobreviveram e grava `lib/l10n/app_de.arb`. O texto depende do modelo, por exemplo:

```json title="lib/l10n/app_de.arb"
{
  "@@locale": "de",
  "greeting": "Hallo, {name}!",
  "cartEmpty": "Dein Warenkorb ist leer."
}
```

</Step>
<Step>

### Verificar se todos os locales estão sincronizados [#verificar-se-todos-os-locales-estão-sincronizados]

```bash
npx @verbatra/cli check
```

```text output
[ok] checking the locales (0.0s)
verbatra check
  de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in sync
```

O `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.

</Step>
<Step>

### Carregar os locales no seu app [#carregar-os-locales-no-seu-app]

Adicione `flutter_localizations`:

```bash
flutter pub add flutter_localizations:"{sdk: flutter}" intl:any
```

Depois, carregue os dois arquivos e exiba a saudação:

```yaml title="pubspec.yaml"
flutter:
  generate: true
```

```yaml title="l10n.yaml"
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
```

```dart title="lib/main.dart"
import '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!`.

</Step>
</Steps>

## O que acabou de acontecer [#o-que-acabou-de-acontecer]

- O `verbatra.lock.json` registra 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](https://verbatra.kreitz-webdev.de/pt-BR/docs/the-lock-file.md).
- Um resultado que perde um placeholder fica retido e nunca é gravado. Veja [Segurança da tradução](https://verbatra.kreitz-webdev.de/pt-BR/docs/translation-safety.md).

Faça commit dos arquivos de locale, do `verbatra.lock.json` e do `verbatra.provenance.json` juntos.

## Opcional: conectar seu agente de programação [#opcional-conectar-seu-agente-de-programação]

<AvailableFrom version="0.12.0" />

```bash
npx @verbatra/cli init --agent
```

Com 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](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/init.md#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:

[Adicionar ao VS Code](vscode:mcp/install?%7B%22name%22%3A%22verbatra%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40verbatra%2Fmcp%22%5D%7D)

## Próximos passos [#próximos-passos]

<Cards>
  <Card title="Adicionar um idioma" href="https://verbatra.kreitz-webdev.de/pt-BR/docs/add-a-language.md" description="Adicione um locale de destino e deixe uma execução preenchê-lo." />
  <Card title="Executar o verbatra na CI" href="https://verbatra.kreitz-webdev.de/pt-BR/docs/ci-and-exit-codes.md" description="Faça um pull request falhar quando um locale divergir." />
  <Card title="Escolher sua stack" href="https://verbatra.kreitz-webdev.de/pt-BR/docs/pick-your-stack.md" description="O id do formato e a estrutura de arquivos de cada outro framework." />
</Cards>
