Ir para o conteúdo principal

Arquitetura

O ecossistema de tradução Champollion é composto por três ferramentas independentes que trabalham juntas através de contratos bem definidos. Nenhuma delas depende da outra em tempo de build. Elas se comunicam através de um formato de plugin de método compartilhado e um contrato de API REST.

As Três Peças​

champollion (este projeto)​

A ferramenta de desenvolvedor open-source. Traduz arquivos de locale usando métodos plugáveis. Zero dependências, configuração opcional, funciona pronto para usar.

Métodos integrados:

  • llm → OpenRouter / qualquer LLM (200+ modelos)
  • llm-coached → LLM + coaching de gramática/dicionário
  • openai → API OpenAI direta (GPT-4o, GPT-4o-mini)
  • anthropic → API Anthropic direta (Claude Sonnet, Haiku, Opus)
  • gemini → API Google Gemini direta (Flash, Pro — tier gratuito disponível)
  • google-translate → Google Cloud Translation API v2
  • deepl → DeepL API com suporte a glossário
  • microsoft-translator → Azure Cognitive Services Translator
  • libretranslate → LibreTranslate auto-hospedado (AGPL, gratuito)
  • api → Tubo fino para qualquer endpoint REST remoto

Eval Harness (projeto complementar)​

Uma ferramenta de pesquisa para desenvolver, testar e fazer benchmark de métodos de tradução. Quando um método atinge qualidade aceitável, o harness exporta um plugin de método — um manifesto method.json e arquivos de coaching opcionais.

O harness nunca é executado dentro do champollion. É uma ferramenta separada que produz saída estática (arquivos JSON). Champollion apenas lê esses arquivos.

→ Eval Harness no GitHub

Champollion Translate (planejado)​

Um serviço de API medido que hospeda métodos de tradução proprietários no servidor — os prompts, dados de coaching e pipelines linguísticos nunca saem do servidor.

Como Eles Se Conectam​

Eval Harness → champollion (exportação unidirecional)​

Contrato: Especificação de Plugin

Champollion Translate → champollion (API em tempo de execução)​

O APIMethod do Champollion é um tubo burro. Ele envia chaves e recebe traduções de volta. Contém zero lógica de tradução e zero conteúdo proprietário.

O Que Cada Peça Sabe Sobre as Outras​

FerramentaSabe sobre champollion?Sabe sobre Champollion Translate?Sabe sobre harness?
champollion(é champollion)Sim — api método chamaNão — apenas lê exportações de plugin
Champollion TranslateSim — atende suas requisições(é Champollion Translate)Não — recebe métodos implantados
Eval HarnessSim — exporta formato de pluginNão — métodos implantados separadamente(é o harness)

Cenários de Usuário​

Cenário 1: Gratuito, zero-config (maioria dos usuários)​

export OPENROUTER_API_KEY=sk-...
npx champollion sync

Usa método llm integrado. Sem plugins, sem Champollion Translate, sem harness.

Cenário 2: Baseline Google Translate​

export GOOGLE_TRANSLATE_API_KEY=AIza...
npx champollion sync

Usa método google-translate integrado. Sem plugins necessários.

Cenário 3: Plugin aberto com coaching incluído​

champollion plugin install ./french-formal-v1/
champollion sync

Plugin tem type: "llm-coached" → champollion usa a chave OpenRouter do usuário. Dados de coaching são locais (sem chamada de servidor).

Cenário 4: Coaching DIY (sem plugin, sem harness)​

champollion.config.json
{
  "pairs": {
    "en:fr": { "method": "llm-coached" }
  }
}

Usuário mantém suas próprias regras de gramática e dicionário em .champollion/coaching/fr.json.

Cartões de Idioma​

Cada idioma no champollion é configurado através de um Cartão de Idioma — um arquivo JSON unificado contendo presets de registro, regras de formalidade, flags de suporte de método, convenções tipográficas, classificação genealógica e dados de referência linguística.

Os cartões são carregados antecipadamente na importação. Cada cartão contém todos os metadados que o mecanismo de tradução e a documentação do desenvolvedor precisam — não há camada de referência separada. Os cartões são gerados a partir de fontes autoritárias (IANA, CLDR, Glottolog, WALS) usando scripts/generate-language-card.mjs e scripts/build-language-tree.mjs, depois curados manualmente para precisão linguística.

Princípios de Design​

  1. Sem dependências circulares. As pontes são unidirecionais.
  2. Champollion é o núcleo leve. Zero dependências, configuração opcional. Plugins e API são aditivos.
  3. Proteção de IP é arquitetural. Técnicas proprietárias ficam no servidor. O pacote npm não envia nada proprietário.
  4. O formato de plugin é o contrato. Tudo flui através de method.json.
  5. Cada ferramenta tem um trabalho. Harness → desenvolver métodos. Champollion Translate → hospedar métodos. Champollion → traduzir arquivos.

Veja Também​