Pular para o conteúdo principal

Especificação do Plugin de Método

Versão: 1.1
Público-alvo: Desenvolvedores de plugins
Schema Canônico: schemas/rosetta-plugin.schema.json

Visão Geral​

O i18n-rosetta usa um sistema de métodos plugáveis. Cada par de idiomas pode usar um método de tradução diferente (LLM, coached, script-converter, etc.). Os métodos são registrados em lib/translate.js e resolvidos por par através de lib/pairs.js.

O trabalho do eval harness é desenvolver, testar e exportar métodos de tradução. O trabalho do i18n-rosetta é consumi-los e executá-los. O harness nunca é executado dentro do rosetta.

Fluxo de Dados​

Formato do Plugin de Método​

Um plugin de método é um único arquivo JSON (method.json) com arquivos opcionais de dados de coaching.

method.json — Obrigatório​

{
  "name": "french-formal-v1",
  "type": "llm-coached",
  "version": "1.0.0",
  "description": "Formally-tuned French with terminology enforcement and grammar coaching",
  "author": "Plugin Author",

  "config": {
    "model": "google/gemini-3.5-flash",
    "register": "formal",
    "batchSize": 30,
    "temperature": 0.2
  },

  "locales": ["fr"],

  "benchmarks": {
    "fr": {
      "date": "2026-05-11T00:00:00Z",
      "corpus_size": 500,
      "exact_match_rate": 0.42,
      "corpus_chrf": 72.3,
      "corpus_bleu": 45.1,
      "model": "google/gemini-3.5-flash",
      "harness_version": "1.0.0"
    }
  },

  "provenance": {
    "resources": [],
    "commercialReady": false,
    "flags": ["license-unclear"]
  },

  "coaching": {
    "dir": "coaching"
  }
}

Referência de Campos​

CampoTipoObrigatórioDescrição
namestring✅Identificador único do método (kebab-case)
typestring✅Tipo de método do Rosetta: llm, llm-coached, api, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini
versionstring✅Versão Semver (ex. 1.0.0)
localesstring[]✅Quais códigos de localidade este método atende (mínimo 1)
descriptionstring—Descrição legível por humanos
authorstring—Quem desenvolveu/testou este método
config.modelstring—Identificador do modelo no OpenRouter
config.registerstring—Registro/tom do idioma de destino
config.batchSizenumber—Chaves por lote de API (1–200, padrão: 30)
config.temperaturenumber—Temperatura do LLM (0.0–2.0, padrão: 0.3)
benchmarksobject—Resultados de benchmark por localidade
provenanceobject—Licenciamento e dependências de recursos
coaching.dirstring—Caminho relativo para o diretório de dados de coaching

Objeto Benchmark (por localidade)​

CampoTipoObrigatórioDescrição
datestring✅Timestamp ISO 8601 da execução do benchmark
corpus_sizenumber✅Número de entradas avaliadas
exact_match_ratenumber✅0.0–1.0, proporção de correspondências exatas (exact matches)
corpus_chrfnumber—Pontuação chrF++ (0–100)
corpus_bleunumber—Pontuação BLEU (0–100)
modelstring✅Modelo usado durante a avaliação (eval)
harness_versionstring✅Versão do evaluation harness utilizada

:::info Quais métricas são exibidas? O comando rosetta status exibe chrF++ e a taxa de correspondência exata (exact match rate) do bloco de benchmark. corpus_bleu é aceito no manifesto, mas atualmente não é exibido ou usado por nenhum comando do rosetta. O Method Leaderboard rastreia chrF++, correspondência exata e taxa de aceitação FST. :::

Objeto Provenance​

O bloco provenance comunica o status de licenciamento dos recursos empacotados do plugin.

CampoTipoPadrãoDescrição
resourcesobject[][]Lista de recursos empacotados com name, license e type
commercialReadybooleanfalseSe o plugin está liberado para distribuição comercial
flagsstring[]["license-unclear"]Flags de status legíveis por máquina

Estado padrão — plugins exportados são enviados com commercialReady: false e flags: ["license-unclear"].

Estado liberado — quando o licenciamento for verificado: defina commercialReady: true e limpe as flags.

Formato de Dados de Coaching​

Se type for llm-coached, o plugin deve incluir arquivos de dados de coaching no subdiretório coaching/.

coaching/<locale>.json​

{
  "grammar_rules": [
    "French adjectives agree in gender and number with the noun they modify",
    "Use 'vous' for formal contexts, 'tu' for informal"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}
CampoTipoObrigatórioDescrição
grammar_rulesstring[]—Regras injetadas em cada prompt do LLM para esta localidade
dictionaryobject—Mapa de termo → tradução. Os termos correspondentes são injetados como terminologia obrigatória.
style_notesstring—Instruções de estilo em formato livre anexadas ao prompt

Estrutura de Diretórios​

french-formal-v1/
  method.json                 # Method manifest with benchmarks
  coaching/
    fr.json                   # Coaching data for French

Para métodos com múltiplas localidades:

european-formal-v2/
  method.json                 # locales: ["fr", "de", "es", "it"]
  coaching/
    fr.json
    de.json
    es.json
    it.json

Como o Rosetta Consome Plugins​

Instalação​

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

Salva em .rosetta/methods/french-formal-v1/.

Configuração​

i18n-rosetta.config.json
{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

:::info Semântica de mesclagem (merge) O plugin define qual método usar (type). A configuração do par ajusta como executá-lo (model, register, batchSize). Se o par definir model, ele substitui o padrão do plugin. :::

Tempo de Execução (Runtime)​

  1. O Rosetta lê method.json de .rosetta/methods/french-formal-v1/
  2. O campo type do plugin define o método de tradução (ex., llm-coached)
  3. Carrega os dados de coaching do diretório coaching/ do plugin
  4. Usa o bloco config para preencher lacunas em modelo/registro/temperatura
  5. O bloco benchmarks é exibido na saída de rosetta status
  6. O bloco provenance é verificado por rosetta provenance em busca de flags de licenciamento

Validação de Schema​

Os manifestos de plugin são validados no momento da instalação em relação a schemas/rosetta-plugin.schema.json.

Referencie o schema no seu method.json para preenchimento automático (autocompletion) na IDE:

{
  "$schema": "./node_modules/i18n-rosetta/schemas/rosetta-plugin.schema.json",
  "name": "my-method-v1"
}

O que NÃO Incluir​

  • ❌ Nenhum código Python ou dependências do harness
  • ❌ Nenhum dado bruto de corpus ou logs de execução
  • ❌ Nenhuma chave de API ou credenciais
  • ❌ Nenhuma configuração do harness
  • ❌ Nenhum template interno de prompt (eles residem nas implementações de método do rosetta)

O plugin é apenas dados: configuração, conteúdo de coaching e resultados de benchmark.

Veja Também​