Ir para o conteúdo principal

Livro de Receitas: Traduzir 30 Idiomas

Escale um projeto de alguns poucos locales para cobertura global. Este livro de receitas o guia pela seleção de métodos, otimização de custos e integração com CI para uma implantação real em múltiplos idiomas.

Cenário: Você tem um app SaaS com en, fr, es. Você precisa adicionar 27 idiomas a mais em três níveis de requisitos de qualidade.

Passo 1: Categorize Seus Idiomas​

Nem todos os 30 idiomas precisam da mesma abordagem. Agrupe-os pela qualidade do método disponível:

NívelIdiomasMétodoPor quê
Nível 1 — Premiumja, ko, zh, de, ptllm (GPT-4o)Mercados de alto valor, gramática nuançada
Nível 2 — Padrãoit, nl, pl, sv, da, fi, no, cs, ro, hu, el, tr, id, ms, th, vi, uk, bggoogle-translateAlto volume, bem suportado pelo Google
Nível 3 — Orientadocrk, oj, mi, hawllm-coached + pluginsBaixo recurso, requerem aplicação de terminologia

Passo 2: Configure Por Par​

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

Nota: Idiomas não listados em pairs herdam defaultMethod: "google-translate". Você não precisa listar todos os 30.

informação

O suporte a crk está em desenvolvimento — veja Suporte a um Idioma de Baixo Recurso para status e diretrizes de contribuição.

Passo 3: Configure as Chaves de API​

Você precisará de ambas as chaves de API para esta configuração:

export OPENROUTER_API_KEY="sk-or-v1-..."
export GOOGLE_TRANSLATE_API_KEY="AIza..."

Passo 4: Faça uma Execução de Teste Primeiro​

Sempre visualize antes de traduzir 30 idiomas:

npx champollion sync --dry

Revise a saída. Ela mostrará:

  • Quais pares usam qual método
  • Quantas chaves são novas/alteradas por locale
  • Chamadas de API estimadas por nível

Passo 5: Execute a Sincronização​

npx champollion sync

Champollion processa cada par independentemente. Os pares do Nível 2 usando Google Translate serão rápidos. Os pares do Nível 1 com LLM serão mais lentos, mas de qualidade superior. Os pares do Nível 3 orientados usam os dados de coaching do plugin.

Atualizações Incrementais​

Após a sincronização inicial, execuções subsequentes traduzem apenas chaves alteradas ou novas:

# Only keys that changed since last sync
npx champollion sync

O arquivo de lock (.champollion.lock) rastreia o que foi traduzido, então você nunca retraduz conteúdo estável.

Passo 6: Audite a Qualidade​

Verifique o status de todos os pares de idiomas:

npx champollion status

Isso produz uma tabela mostrando o método, modelo, nível de qualidade de cada par e se dados de coaching ou pontuações de benchmark estão disponíveis.

A saída respeitou seus registros?​

No Passo 2 você declarou um registro por idioma — "Polite/formal" para japonês, "Formal (Sie)" para alemão. (Novo no termo? O glossário explica em linguagem simples.) Essas instruções entram no prompt de tradução, mas um prompt é um pedido, não uma garantia.

O harness MT Eval Arena — a mesma ferramenta que alimenta o leaderboard público — pode medir a aderência de registro e estilo em uma amostra de suas traduções. Suas métricas de estilo de escrita verificam cada saída contra o registro esperado (marcadores formais/informais, pronomes T–V, contrações, desvio de comprimento de sentença) e relatam um style_consistency_rate em toda a execução. Você também pode apontá-la para um perfil de voz de marca personalizado com --style-profile.

# install the harness, then run your sample corpus through it
curl -fsSL champollion.dev/harness | bash
mt-eval run --corpus my-sample.json --style-profile brand-voice.json

Duas ressalvas honestas: essas métricas são informacionais (nunca entram na pontuação composta do leaderboard), e a detecção de formalidade é baseada em marcadores — um detector de desvio, não um julgamento humano. Detalhes e definições de métricas: Métricas de estilo de escrita e registro.

Passo 7: Integração com CI​

Adicione ao seu fluxo de trabalho do GitHub Actions para que as traduções permaneçam atualizadas a cada push:

.github/workflows/i18n-sync.yml
name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx champollion sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

Estimativa de Custos​

Para um projeto com 500 chaves de origem em 30 idiomas:

NívelIdiomasMétodoCusto Aproximado
Nível 1 (5 idiomas)ja, ko, zh, de, ptGPT-4o~$2,50/sincronização completa
Nível 2 (18 idiomas)it, nl, pl, etc.Google Translate~$0,90/sincronização completa
Nível 3 (4 idiomas)crk, oj, mi, hawGPT-4o-mini orientado~$0,40/sincronização completa
Total30 idiomasMisto~$3,80/sincronização completa

Sincronizações incrementais (5–20 chaves alteradas) custam uma fração de uma sincronização completa.

Veja Também​