Skip to main content

Architecture

The Rosetta translation ecosystem is three independent tools that work together through well-defined contracts. None of them depend on each other at build time. They communicate through a shared method plugin format and a REST API contract.

The Three Pieces​

i18n-rosetta (this project)​

The open-source developer tool. Translates locale files using pluggable methods. Zero dependencies, config-optional, works out of the box.

Built-in methods:

  • llm → OpenRouter / any LLM
  • llm-coached → LLM + grammar/dictionary coaching
  • google-translate → Google Cloud Translation API
  • api → Thin pipe to any remote API

Eval Harness (companion project)​

A research tool for developing, testing, and benchmarking translation methods. When a method reaches acceptable quality, the harness exports a method plugin — a method.json manifest and optional coaching data files.

The harness never runs inside rosetta. It's a separate tool that produces static output (JSON files). Rosetta just reads those files.

→ Eval Harness on GitHub

Rosetta Translate (planned)​

A metered API service that hosts proprietary translation methods server-side — the prompts, coaching data, and linguistic pipelines never leave the server.

How They Connect​

Eval Harness → i18n-rosetta (one-way export)​

Contract: Plugin Specification

Rosetta Translate → i18n-rosetta (API at runtime)​

Rosetta's APIMethod is a dumb pipe. It sends keys out and receives translations back. It contains zero translation logic and zero proprietary content.

What Each Piece Knows About the Others​

ToolKnows about rosetta?Knows about Rosetta Translate?Knows about harness?
i18n-rosetta(is rosetta)Yes — api method calls itNo — just reads plugin exports
Rosetta TranslateYes — serves its requests(is Rosetta Translate)No — receives deployed methods
Eval HarnessYes — exports plugin formatNo — methods deployed separately(is the harness)

User Scenarios​

Scenario 1: Free, zero-config (most users)​

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

Uses built-in llm method. No plugins, no Rosetta Translate, no harness.

Scenario 2: Google Translate baseline​

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

Uses built-in google-translate method. No plugins needed.

Scenario 3: Open plugin with bundled coaching​

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

Plugin has type: "llm-coached" → rosetta uses user's own OpenRouter key. Coaching data is local (no server call).

Scenario 4: DIY coaching (no plugin, no harness)​

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

User maintains their own grammar rules and dictionary in .rosetta/coaching/fr.json.

Design Principles​

  1. No circular dependencies. The bridges are one-way.
  2. Rosetta is the lightweight core. Zero dependencies, config-optional. Plugins and API are additive.
  3. IP protection is architectural. Proprietary techniques stay server-side. The npm package ships nothing proprietary.
  4. The plugin format is the contract. Everything flows through method.json.
  5. Each tool has one job. Harness → develop methods. Rosetta Translate → host methods. Rosetta → translate files.