Traduzir

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, 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.

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

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 com --claude, ou Codex 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 ({ 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

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

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.

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

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.

blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout

- 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

• 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.
• 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 <n> — sessões de agente em paralelo. O padrão é 4; máximo 16.
• --locale <codes> — 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 <seconds> — 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.