---
order: 4
section: guides
title: Tradução
description: >-
  Como o scribe translate funciona: hash de conteúdo desatualizado, Gemini,
  validação de saída, relatórios de custos e ferramentas de revisão.
noindex: false
canonicalPath: /pt-BR/docs/translation
---
O Scribe traduz o conteúdo original em inglês para todos os outros idiomas usando um LLM (Gemini) e armazena os resultados no SQLite. Você nunca edita os arquivos de localização. Basta editar o inglês, rodar `scribe translate` e fazer o commit do armazenamento.  

## O que é traduzido

Exatamente duas coisas vão para o tradutor por documento:

1. Campos do frontmatter marcados com `field.translatable()`, incluindo campos aninhados em arrays e objetos.
2. O corpo do MDX.

Todo o resto (`field.structural()`, relações, campos integrados) é copiado do documento em inglês no momento do carregamento. Com `slugStrategy: "localized"`, o tradutor também produz um slug de URL por idioma (kebab-case em ASCII, transliterado para idiomas não latinos).

Um idioma que você ainda não traduziu não é um beco sem saída na execução: `resolve()` entrega a tradução mais próxima disponível através da [cadeia de fallback de idiomas](/docs/configuration#locale-fallback-chains) (por exemplo, `pt-BR` faz o fallback para `pt` e, em seguida, para o idioma padrão). Assim, você pode lançar novos idiomas gradualmente.

## Controle de desatualização

Cada tradução armazenada registra um hash SHA-256 do conteúdo traduzível em inglês que lhe serviu de base. O `scribe translate` só retraduz uma página quando:

- não existe tradução para aquele idioma (**ausente**), ou
- o conteúdo traduzível em inglês mudou desde então (**desatualizado**).

Editar um campo estrutural ou uma entrada no `_redirects.json` **não** marca as traduções como desatualizadas (esses campos não são traduzidos).

## Validação de saída

Uma tradução só é salva definitivamente se passar por duas verificações:

1. O corpo MDX retornado precisa ser analisado corretamente (após normalizar artefatos de escape e as aspas de atributos JSX, algo que o modelo às vezes erra).
2. O frontmatter retornado deve ser revalidado em relação ao seu esquema Zod completo.

Itens que falham na validação passam por uma nova tentativa automática no final da execução. Os erros de validação retornam ao modelo para que ele os corrija (as execuções em lote fazem essa tentativa como um trabalho em lote extra, mantendo a mesma taxa). Qualquer coisa que falhe novamente é listada no resumo final com seu novo erro e o comando sai com status de erro. Como uma saída defeituosa do modelo nunca chega ao armazenamento, ela jamais alcança a produção.

## Como executar

```bash
export GEMINI_API_KEY=...        # lido também de .env / .env.local

scribe status                     # cobertura por tipo e idioma
scribe translate                  # seletor interativo em um TTY
scribe translate --locale fr de   # idiomas específicos
scribe translate --preset active  # um grupo localePresets da configuração
scribe translate --type blog      # um tipo de conteúdo (separado por vírgulas: --type blog,glossary)
scribe translate --slug my-post   # um documento
scribe translate --dry-run        # mostra a lista de trabalho + estimativa de tokens/custo, sem gravar nada
scribe translate --force          # retraduz mesmo quando os hashes conferem
scribe translate --strategy missing-only   # ignora desatualizados, preenche apenas lacunas
scribe translate --batch          # força o modo em lote (o padrão)
scribe translate --direct         # chamadas de API por página, resultados imediatos
scribe translate --resume         # retoma trabalhos em lote pendentes, não envia nada novo
scribe translate --concurrency 5  # requisições paralelas (apenas no modo direto)
scribe translate --model gemini-3.1-pro
```

Rodando no terminal, o `scribe translate` exibe uma interface de progresso em tempo real com o status dos trabalhos em lote, resultados por item, contagem contínua de tokens e um custo estimado em dólares. Os tokens de raciocínio (thinking tokens) estão incluídos no uso reportado, fazendo com que a estimativa bata exatamente com o que o Google cobra. Passe `--no-progress` (ou execute de forma não interativa, como em uma CI) para obter logs simples em formato texto.

O comando `--dry-run` imprime a lista de trabalho sem gravar absolutamente nada, relatando uma estimativa de tokens e o custo em dólares por item e no total, calculados a partir do prompt real e do tamanho do payload em inglês. Com `--batch`, a estimativa já aplica o desconto de lote, servindo de prévia confiável para o custo da execução real.

Depois disso, faça o commit do arquivo `.scribe/store.sqlite`.

## Modo em lote e retomada

Por padrão, toda a lista de trabalho passa pela Batch API do Gemini, operando com 50% do custo em tokens das chamadas diretas. O Scribe planeja todas as requisições antecipadamente (um trabalho por modelo, segmentado no caso de listas gigantes), envia todos os trabalhos de uma vez, verifica o status deles em conjunto e armazena os resultados de cada trabalho assim que concluídos. Trabalhos em lote costumam terminar em minutos, mas o Google só garante a conclusão em 24 horas. Por esse motivo, o comando aguarda em vez de transmitir os resultados página a página.

Cada trabalho fica registrado no banco SQLite antes mesmo da verificação começar, junto com um "retrato" (snapshot) da fonte em inglês a partir da qual cada item foi enviado. Isso faz com que as execuções possam ser interrompidas com segurança:

- Se você sair durante a verificação de status (Ctrl+C), nada será perdido.
- O comando `scribe translate --resume` verifica os trabalhos pendentes, processa os finalizados e não envia nada novo.
- Executar o `scribe translate` da forma normal também retoma primeiro os trabalhos pendentes. Itens que já estão em processamento nunca são enviados duas vezes.
- Editar uma página em inglês enquanto seu lote está em andamento não é um problema: o resultado é salvo com base no snapshot do qual foi traduzido e, na próxima execução, será detectado como desatualizado.

Prefere resultados imediatos e página a página pelo preço normal? Use `--direct`. Essa opção restaura as chamadas de API por página aproveitando o paralelismo de `--concurrency`. No terminal, o seletor interativo oferece a mesma escolha. Erros temporários de API (429, 5xx, instabilidades de rede) acionam novas tentativas automáticas com recuo exponencial em ambos os modos.

## Orientando o tradutor

O prompt integrado foi construído com foco em transriação, não em tradução literal. O modelo escreve como um copywriter nativo produzindo uma edição localizada: ele recria expressões idiomáticas e jogos de palavras em vez de traduzi-los ao pé da letra, aplicando as convenções tipográficas locais (aspas, apóstrofos, espaçamento de pontuação). Suas diretrizes em `context`, `rules` e `prompt` são adicionadas a essa base.

Padrões globais do projeto e substituições específicas por tipo:

```ts
export default defineConfig({
  translate: {
    context: "MyBrand é um SaaS B2B. Nunca traduza o nome da marca MyBrand.",
    rules: ["Mantenha os números e as estatísticas precisos."],
  },
  types: [
    defineContentType({
      id: "blog",
      // ...
      translate: {
        rules: [
          "Preserve todas as tags, props e URLs de componentes MDX/JSX exatamente como estão.",
          "Traduza o texto âncora do link; nunca altere os caminhos de href.",
        ],
      },
    }),
  ],
});
```

| Opção | Escopo | Descrição |
| --- | --- | --- |
| `context` | projeto + tipo | Contexto da marca/domínio adicionado antes de cada requisição (contextos de projeto e tipo são unidos). |
| `rules` | projeto + tipo | Regras adicionais anexadas aos padrões. |
| `prompt` | projeto ou tipo | Instruções de localização extras, inseridas antes da diretiva do idioma de destino (o nome e o código do idioma são sempre adicionados). |
| `defaultModel` / `model` | projeto / tipo | ID do modelo Gemini. Padrão: `gemini-3.1-pro` (também pode ser sobrescrito via variável de ambiente `PROSE_GEMINI_MODEL` ou pela flag `--model`). |

As regras nativas (sempre aplicadas) incluem não traduzir nomes de marcas, a menos que tenham um nome local muito conhecido no mercado-alvo, retornar corpos MDX com quebras de linha reais (e não escapar com `\n`) e corrigir as aspas de atributos JSX quando os valores contêm aspas duplas.

## Revisando traduções

```bash
scribe history blog my-post fr    # linha do tempo de snapshots em EN para uma página específica
scribe studio                     # interface web apenas para leitura na porta :3600
```

Toda tradução é vinculada ao snapshot da fonte original em inglês que a gerou (armazenado no mesmo arquivo SQLite). Assim, você pode verificar quando, a partir do que e com qual modelo uma página foi traduzida. O comando `scribe history` exibe essa linha do tempo, enquanto o estúdio mostra a cobertura por idioma, a lista de itens pendentes ou desatualizados e os detalhes de cada documento (com o snapshot lado a lado com a tradução guardada).

## Predefinições de idioma

Para lançamentos graduais, crie grupos de idiomas na configuração e direcione os comandos usando `--preset`:

```ts
localePresets: {
  active: ["fr", "es", "ja"],
  ultraLight: ["fr"],
}
```

```bash
scribe translate --preset ultraLight
```