---
title: "Início rápido com React"
description: "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."
type: "tutorial"
---
# 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](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`.

</Step>
<Step>

### Adicionar um arquivo de locale de origem [#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:

```json title="locales/en.json"
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}
```

</Step>
<Step>

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

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

</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 `locales/de.json`. O texto depende do modelo, por exemplo:

```json title="locales/de.json"
{
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "empty": "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 `react-i18next`:

```bash
npm install i18next react-i18next
```

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

```ts title="src/i18n.ts"
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 } },
});
```

```tsx title="src/Greeting.tsx"
import { useTranslation } from "react-i18next";

export function Greeting() {
  const { t } = useTranslation();
  return <p>{t("greeting", { name: "Ada" })}</p>;
}
```

```tsx title="src/main.tsx"
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!`.

</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>
