Pular para o conteúdo principal

Arquitetura

O ecossistema de tradução Rosetta é composto por três ferramentas independentes que trabalham juntas por meio de contratos bem definidos. Nenhuma delas depende das outras em tempo de compilação (build time). Elas se comunicam através de um formato de plugin de método compartilhado e um contrato de API REST.

Os Três Componentes​

i18n-rosetta (este projeto)​

A ferramenta open-source para desenvolvedores. Traduz arquivos de localidade (locale) usando métodos conectáveis. Zero dependências, configuração opcional, funciona de imediato (out of the box).

Métodos integrados:

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

Eval Harness (projeto complementar)​

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

O harness nunca é executado dentro do rosetta. É uma ferramenta separada que produz saídas estáticas (arquivos JSON). O Rosetta apenas lê esses arquivos.

→ Eval Harness no GitHub

Rosetta Translate (planejado)​

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

Como Eles se Conectam​

Eval Harness → i18n-rosetta (exportação unidirecional)​

Contrato: Especificação do Plugin

Rosetta Translate → i18n-rosetta (API em tempo de execução)​

O APIMethod do Rosetta é um canal passivo (dumb pipe). Ele envia chaves e recebe traduções de volta. Ele contém zero lógica de tradução e zero conteúdo proprietário.

O Que Cada Componente Sabe Sobre os Outros​

FerramentaConhece o rosetta?Conhece o Rosetta Translate?Conhece o harness?
i18n-rosetta(é o rosetta)Sim — o método api o chamaNão — apenas lê as exportações de plugins
Rosetta TranslateSim — atende às suas requisições(é o Rosetta Translate)Não — recebe métodos implantados
Eval HarnessSim — exporta o formato de pluginNão — métodos implantados separadamente(é o harness)

Cenários de Usuário​

Cenário 1: Gratuito, zero configuração (maioria dos usuários)​

export OPENROUTER_API_KEY=sk-...
npx i18n-rosetta sync

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

Cenário 2: Baseline do Google Translate​

export GOOGLE_TRANSLATE_API_KEY=AIza...
npx i18n-rosetta sync

Usa o método google-translate integrado. Não são necessários plugins.

Cenário 3: Plugin aberto com orientação embutida​

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

O plugin tem type: "llm-coached" → o rosetta usa a própria chave do OpenRouter do usuário. Os dados de orientação são locais (sem chamada ao servidor).

Cenário 4: Orientação DIY (sem plugin, sem harness)​

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

O usuário mantém suas próprias regras gramaticais e dicionário em .rosetta/coaching/fr.json.

Language Cards​

Cada idioma no rosetta é configurado através de um Language Card — um arquivo JSON contendo predefinições de registro, regras de formalidade, flags de suporte a métodos e convenções tipográficas. Os Language Cards são a configuração por idioma que orienta a tradução baseada em registro (register-steered translation).

Os cards são divididos em duas camadas (tiers) para desempenho em escala (visando mais de 700 idiomas):

  • Camada de tempo de execução (Runtime tier) (language-cards/): Carregada antecipadamente (eagerly) — os campos que o mecanismo de tradução precisa (registros, formalidade, suporte a métodos, regras tipográficas).
  • Camada de referência (Reference tier) (language-reference/): Carregada sob demanda (lazily) — documentação para desenvolvedores (desafios linguísticos, família de idiomas, recursos de PNL).

Ambas as camadas são geradas a partir de fontes confiáveis (IANA, CLDR, Glottolog) usando scripts/generate-language-card.mjs e, em seguida, curadas por humanos para precisão linguística.

Princípios de Design​

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

Veja Também​