Skip to main content

Method Plugin Specification

Version: 1.1
Audience: Plugin developers
Canonical Schema: schemas/rosetta-plugin.schema.json

Overview​

i18n-rosetta uses a pluggable method system. Each language pair can use a different translation method (LLM, coached, script-converter, etc.). Methods are registered in lib/translate.js and resolved per-pair via lib/pairs.js.

The eval harness's job is to develop, test, and export translation methods. i18n-rosetta's job is to consume and execute them. The harness never runs inside rosetta.

Data Flow​

Method Plugin Format​

A method plugin is a single JSON file (method.json) with optional coaching data files.

method.json — Required​

{
  "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": 80,
    "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"
  }
}

Field Reference​

FieldTypeRequiredDescription
namestring✅Unique method identifier (kebab-case)
typestring✅Rosetta method type: llm, llm-coached, api, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini
versionstring✅Semver version (e.g. 1.0.0)
localesstring[]✅Which locale codes this method targets (minimum 1)
descriptionstring—Human-readable description
authorstring—Who developed/tested this method
config.modelstring—OpenRouter model identifier
config.registerstring—Target language register/tone
config.batchSizenumber—Keys per API batch (1–200, default: 80)
config.temperaturenumber—LLM temperature (0.0–2.0, default: 0.3)
benchmarksobject—Per-locale benchmark results
provenanceobject—Licensing and resource dependencies
coaching.dirstring—Relative path to coaching data directory

Benchmark Object (per locale)​

FieldTypeRequiredDescription
datestring✅ISO 8601 timestamp of the benchmark run
corpus_sizenumber✅Number of entries evaluated
exact_match_ratenumber✅0.0–1.0, proportion of exact matches
corpus_chrfnumber—chrF++ score (0–100)
corpus_bleunumber—BLEU score (0–100)
modelstring✅Model used during eval
harness_versionstring✅Version of the evaluation harness used

:::info Which metrics are displayed? The rosetta status command displays chrF++ and exact match rate from the benchmark block. corpus_bleu is accepted in the manifest but is not currently displayed or used by any rosetta command. The Method Leaderboard tracks chrF++, exact match, and FST acceptance rate. :::

Provenance Object​

The provenance block communicates the licensing status of the plugin's bundled resources.

FieldTypeDefaultDescription
resourcesobject[][]List of bundled resources with name, license, and type
commercialReadybooleanfalseWhether the plugin is cleared for commercial distribution
flagsstring[]["license-unclear"]Machine-readable status flags

Default state — exported plugins ship with commercialReady: false and flags: ["license-unclear"].

Cleared state — when licensing has been verified: set commercialReady: true and clear the flags.

Coaching Data Format​

If type is llm-coached, the plugin should include coaching data files in the coaching/ subdirectory.

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."
}
FieldTypeRequiredDescription
grammar_rulesstring[]—Rules injected into every LLM prompt for this locale
dictionaryobject—Term → translation map. Matched terms are injected as required terminology.
style_notesstring—Freeform style instructions appended to the prompt

Directory Structure​

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

For multi-locale methods:

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

How Rosetta Consumes Plugins​

Installation​

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

Saves to .rosetta/methods/french-formal-v1/.

Configuration​

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

:::info Merge semantics The plugin defines what method to use (type). The pair config tunes how to run it (model, register, batchSize). If the pair sets model, it overrides the plugin's default. :::

Runtime​

  1. Rosetta reads method.json from .rosetta/methods/french-formal-v1/
  2. The plugin's type field sets the translation method (e.g., llm-coached)
  3. Loads coaching data from the plugin's coaching/ directory
  4. Uses the config block to fill gaps in model/register/temperature
  5. The benchmarks block is displayed in rosetta status output
  6. The provenance block is checked by rosetta provenance for licensing flags

Schema Validation​

Plugin manifests are validated at install time against schemas/rosetta-plugin.schema.json.

Reference the schema in your method.json for IDE autocompletion:

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

What NOT to Include​

  • ❌ No Python code or harness dependencies
  • ❌ No raw corpus data or run logs
  • ❌ No API keys or credentials
  • ❌ No harness configuration
  • ❌ No internal prompt templates (those live in rosetta's method implementations)

The plugin is data only: configuration, coaching content, and benchmark results.

See Also​