--- title: Traduzir description: >- O blume translate preenche seus locales com um agente de IA — ele encontra as páginas que estão faltando ou desatualizadas em cada idioma, as traduz com a CLI de agente que você já tem e dá ao CI um portão que falha quando as traduções ficam dessincronizadas. --- Depois de ativar o [i18n](/docs/content/i18n), cada edição em uma página de origem desatualiza silenciosamente suas traduções. O `blume translate` fecha esse ciclo: ele calcula exatamente quais páginas estão faltando ou desatualizadas em cada locale, as traduz em modo headless com uma CLI de agente local e registra o que fez em um livro de registro versionado, para que a próxima execução — e o CI — saibam o que está atualizado. ```bash blume translate --claude ``` ``` blume translate 3 item(s) · 2 locale(s) · Claude Code ✔ docs/guides/install.mdx → fr 24.2s $0.11 ✔ docs/guides/install.mdx → de 22.8s $0.10 ✔ meta titles (2) → de 4.1s $0.01 Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22 ``` ## Como funciona [#how-it-works] O Blume é o dono do pipeline; o agente só traduz texto. Para cada arquivo que precisa de trabalho, o Blume monta um prompt de tradução, executa a CLI do agente em modo headless com as ferramentas de arquivo, shell e web desativadas, valida a estrutura da resposta e escreve ele mesmo o arquivo de destino — [Claude Code](https://claude.com/claude-code) com `--claude`, ou [Codex](https://developers.openai.com/codex/cli) com `--codex`. O Blume não guarda chaves de API e não chama nenhum modelo por conta própria. Cada escrita validada é registrada em `blume.translations.json` na raiz do projeto: para cada arquivo de origem e locale, um hash da origem no momento em que foi traduzida. **Faça commit desse arquivo.** É assim que uma nova execução distingue entre "já traduzido" e "traduzido, mas a origem mudou desde então" — e é o que torna o portão de CI possível. O livro de registro é gravado após cada arquivo concluído, então interromper uma execução longa (Ctrl+C) perde, no máximo, as traduções que estavam em andamento — a execução seguinte retoma de onde você parou. Por padrão, os arquivos são processados 4 por vez; aumente esse valor com `--concurrency` se a sua máquina e os limites de taxa do agente permitirem. As novas execuções são incrementais: uma origem que não mudou desde a última tradução é ignorada, então rodar `blume translate` depois de editar uma página traduz uma página por locale. Quando uma página desatualizada é retraduzida, o agente vê a tradução existente e é instruído a manter seu registro, dialeto e terminologia — uma edição de um parágrafo na origem produz um diff de tradução de um parágrafo, não uma reescrita do zero. Uma primeira tradução não tem precedente para seguir, então fixe a escolha desde o início com [`style` no locale](/docs/content/i18n) (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`). Essa orientação acompanha todo prompt de tradução e, quando uma tradução existente discorda dela, o `style` vence — assim, uma retradução também empurra as páginas mais antigas na direção do estilo configurado. ## O que é traduzido [#what-gets-translated] - **Páginas** — arquivos `.md`/`.mdx` no locale padrão. O agente traduz a prosa e apenas os valores de frontmatter visíveis para humanos (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`). Os destinos seguem o seu parser: `fr/guides/install.mdx` com `dir`, `guides/install.fr.mdx` com `dot`. - **Títulos de navegação de pastas** — com o parser `dir`, os títulos [`meta.ts`](/docs/content/meta) necessários de cada locale são traduzidos em uma única chamada em lote, e o `meta.ts` gerado por locale copia todas as outras chaves (`order`, `pages`, `icon`, `collapsed`) sem alteração, para que a barra lateral do locale mantenha sua ordenação. As traduções que você escreveu à mão são **adotadas, nunca sobrescritas**: uma tradução que existe mas não tem entrada no livro de registro é marcada como atual e deixada intacta. Só o `--force` a retraduz. ## Validação [#validation] A estrutura nunca é confiada ao agente. Antes de escrever, o Blume verifica cada resposta e reconstrói o arquivo a partir da origem: - O frontmatter é reconstruído a partir dos dados do arquivo de origem, com apenas os seis valores traduzíveis sobrepostos — as chaves que o agente inventou são descartadas, as chaves que ele apagou são restauradas, e `slug`, `icon`, `order` e as datas são, por construção, idênticas às da origem. - O número de blocos de código precisa corresponder ao da origem, o corpo não pode estar vazio e o frontmatter precisa ser analisável. - Cada título é fixado ao id de âncora do título de origem com um [marcador `[#id]`](/docs/content/syntax#custom-anchors) no final, a menos que a tradução já fixe um, para que os links `#fragment` resolvam de forma idêntica em todos os idiomas. Os títulos são pareados por posição, então uma tradução cuja estrutura de títulos não corresponde à da origem não recebe nenhum marcador. Uma resposta que falha na validação não escreve nada — o item é reportado como falho e a execução segue em frente. Tudo o que teve sucesso permanece registrado no livro de registro, então uma nova execução repete apenas as falhas. ## Falhar o CI [#failing-ci] O `blume translate --check` é o portão somente leitura: ele reporta todos os pares faltando e desatualizados e sai com código diferente de zero quando há dessincronização, sem executar um agente nem escrever nada. ```bash blume translate --check # exit 1 when translations are missing or stale blume translate --check --json # machine-readable drift report on stdout ``` ```yaml .github/workflows/translations.yml - run: npx blume translate --check ``` O relatório JSON tem o mesmo formato `diagnostics` + `summary` que o `blume validate --json`, o `blume audit --json` e o `blume eval --json`, com a dessincronização agrupada por locale. As traduções escritas à mão (não registradas) nunca fazem o portão falhar. ## Limitações [#limitations] - A tradução de títulos de meta existe apenas no parser `dir` — o parser `dot` não tem mecanismo de `meta.ts` por locale. Um `meta.ts` que exporta uma função como default é ignorado com um aviso; escreva a cópia desse locale à mão. - As origens remotas e vindas de CMS são ignoradas: não existe um arquivo local onde escrever a tradução. - Os rótulos das abas do cabeçalho vivem em `blume.config.ts`, não no conteúdo — localize-os lá com [mapas de rótulos por locale](/docs/content/navigation#tabs). - A qualidade da tradução é do agente. Revise o resultado como qualquer outra contribuição — o livro de registro só garante atualidade, não fluência. ## Flags - `--claude` / `--codex` — qual CLI de agente traduz. Exatamente uma é obrigatória (exceto com `--check`). - `--check` — reportar a dessincronização e sair com código diferente de zero, sem escrever nada. - `--concurrency ` — sessões de agente em paralelo. O padrão é `4`; máximo `16`. - `--locale ` — locales de destino separados por vírgula (por padrão, todos os locales não padrão). - `--force` — retraduzir tudo, incluindo arquivos atualizados e escritos à mão. - `--timeout ` — limite de tempo do agente por arquivo. O padrão é `600`; o teto existe para pegar agentes travados, então páginas grandes têm espaço para terminar. - `--json` — emitir o relatório em JSON no stdout, nos dois modos.