Ir para o conteúdo principal

Guia do Agente: Usando champollion

champollion é uma ferramenta CLI que traduz os arquivos de locale do seu app com um único comando. Este guia é para agentes de IA (ou desenvolvedores trabalhando com agentes de IA) que querem ir de zero a arquivos de locale traduzidos rapidamente.

:::tip Já familiarizado? Se você só precisa de comandos, vá para a Referência CLI. Se você quer construir e fazer benchmark de um método de tradução, veja o Guia do Agente Arena. :::

Configuração do Ambiente​

# No global install needed — npx runs it directly
npx champollion sync

Requisitos:

  • Node.js 18+
  • Uma chave de API para seu provedor de tradução

Configuração da chave de API — champollion precisa de pelo menos uma chave dependendo de quais métodos você usa:

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Champollion lê .env automaticamente. Obtenha uma chave OpenRouter em openrouter.ai/keys.

Primeira Sincronização​

Champollion detecta automaticamente seus arquivos de locale, seu formato (JSON, TOML, YAML, PO) e seus idiomas de destino:

npx champollion sync

O que acontece:

  1. Carrega champollion.config.json (ou detecta automaticamente as configurações)
  2. Escaneia seu arquivo de locale de origem, achata chaves aninhadas
  3. Compara contra .champollion.lock (hashes SHA-256 de valores previamente traduzidos)
  4. Verifica .champollion/tm.json para traduções em cache (Memória de Tradução)
  5. Traduz apenas chaves alteradas, ausentes ou obsoletas via o método configurado
  6. Executa o quality gate (5 verificações) em cada tradução
  7. Escreve traduções aprovadas no arquivo de locale de destino
  8. Atualiza o arquivo de lock e cache de TM

Em uma re-execução típica após alterar uma chave, a etapa 4 serve 142 chaves do cache e a etapa 5 traduz 1 chave. É por isso que sincronizações subsequentes são rápidas e baratas.

Configuração​

Crie champollion.config.json na raiz do seu projeto:

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

Campos principais:

CampoPropósitoPadrão
inputLocaleIdioma de origemen
pairsMapa de origem→destino com configuração de método(obrigatório)
localesDirOnde os arquivos de locale vivem(detectado automaticamente)
modelModelo LLM para métodos llm/llm-coachedgoogle/gemini-2.5-flash
batchSizeChaves por chamada de API80 (LLM), 128 (Google)
jsonConcurrencyTraduções paralelas de locale para chaves JSON200
contentConcurrencyChamadas de API paralelas para tradução de conteúdo48

Referência completa: Configuração

Métodos de Tradução​

MétodoQuando usarCustoChave de API necessária
llmPropósito geral, bom para idiomas bem-recursosPor token (dependente do modelo)OPENROUTER_API_KEY
llm-coachedQuando você tem regras de gramática/dicionário para o idioma de destinoPor token + contexto de coachingOPENROUTER_API_KEY
google-translateIdiomas de alto recurso onde GT funciona bem$20/milhão de caracteresGOOGLE_TRANSLATE_API_KEY
apiPipeline customizado hospedado atrás de um endpoint HTTPDeterminado pelo servidorNenhum (endpoint cuida da autenticação)
pluginMétodo pré-empacotado instalado localmenteVariaVaria

Detalhes: Métodos de Tradução

Dados de Coaching​

Para pares llm-coached, dados de coaching orientam o LLM com conhecimento linguístico explícito. Crie um arquivo de coaching:

coaching/fr.json
{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

Referencie-o na configuração do seu par:

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

O quality gate verifica que os termos do dicionário realmente aparecem na saída — violações são registradas como avisos [TERM].

Detalhes: Dados de Coaching

Quality Gate​

Cada tradução passa por cinco verificações automatizadas antes de ser escrita no disco:

VerificaçãoO que detectaExemplo
Vazio/em brancoModelo não retornou nada""
Echo de origemModelo retornou a entrada em inglês inalterada"Welcome" para japonês
Loop de alucinaçãoTrigramas repetidos"Qo' Qo' Qo' Qo'"
Inflação de comprimentoSaída é 4×+ mais longa que a origemOrigem de 10 caracteres → saída de 50 caracteres
Conformidade de scriptScript errado para o localeTexto latino para locale árabe

Falhas são registradas com prefixo [GATE]. Sem fallbacks silenciosos — se uma tradução falhar, é reportada, não silenciosamente aceita.

Detalhes: Quality Gate

Memória de Tradução​

Champollion cacheia traduções em .champollion/tm.json, indexadas por texto de origem + locale + método. Em sincronizações subsequentes, chaves inalteradas são servidas do cache — sem chamada de API, sem custo.

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

Para contornar o cache em uma execução: npx champollion sync --no-tm

Detalhes: Memória de Tradução

Arquivos Gerados​

Champollion cria vários arquivos no seu projeto. Saiba o que são para não deletar ou fazer commit acidentalmente dos errados:

ArquivoPropósitoGit?
.champollion.lockHashes SHA-256 de valores de origem traduzidos (detecção de mudanças)Sim — faça commit deste
.champollion-content.lockMesmo, mas para arquivos de conteúdo Markdown/MDXSim — faça commit deste
.champollion/tm.jsonCache de Memória de TraduçãoSim — faça commit deste (economiza custos de API para o time)
.champollion/coaching/Diretório de dados de coachingSim — este é seu conhecimento linguístico
champollion.config.jsonConfiguração do projetoSim — faça commit deste

Padrões Comuns​

Traduzir um par de idiomas:

npx champollion sync --pair en-fr

Traduzir todos os pares configurados:

npx champollion sync

Champollion traduz todos os locales em paralelo. Com cache de TM, apenas chaves alteradas atingem a API.

Modo de conteúdo (Markdown/MDX para Docusaurus, Hugo, etc.):

npx champollion sync --content

Traduz docs, posts de blog e arquivos de conteúdo junto com JSON de locale. Usa concorrência paralela (padrão: 48 chamadas de API simultâneas). Ajuste com --content-concurrency.

Dry run (visualizar sem escrever):

npx champollion sync --dry-run

Forçar re-tradução de chaves específicas:

npx champollion sync --force-keys "hero.title,nav.about"

Forçar re-tradução de todos os arquivos de conteúdo:

npx champollion sync --force-content

Verificar status de tradução:

npx champollion status

Mostra cobertura, níveis de qualidade e informações de plugin para cada par.

Auditar fallbacks não traduzidos:

npx champollion audit

Lista todos os valores de fallback [EN] que precisam de tradução.

Solução de Problemas​

ProblemaSolução
OPENROUTER_API_KEY not setExporte a chave ou adicione-a a .env na raiz do seu projeto
No locale files foundDefina localesDir na config, ou garanta que seus arquivos de locale correspondam à nomenclatura padrão (en.json, fr.json)
[GATE] Script compliance failedSeu locale de destino recebeu texto latino em vez do script esperado — tente um modelo diferente ou adicione dados de coaching
[GATE] Source echoO modelo retornou inglês inalterado — dados de coaching ou um modelo diferente geralmente corrigem isso
Todas as traduções em cacheExecute com --no-tm para contornar o cache, ou --force-keys para chaves específicas
Conflitos de arquivo de lock.champollion.lock usa hashes SHA-256 — conflitos de merge são seguros de resolver mantendo qualquer versão, depois re-executando sync

Próximos Passos​