Skip to main content

Architecture

The Champollion 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​

champollion (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 (200+ models)
  • llm-coached → LLM + grammar/dictionary coaching
  • openai → Direct OpenAI API (GPT-4o, GPT-4o-mini)
  • anthropic → Direct Anthropic API (Claude Sonnet, Haiku, Opus)
  • gemini → Direct Google Gemini API (Flash, Pro — free tier available)
  • google-translate → Google Cloud Translation API v2
  • deepl → DeepL API with glossary support
  • microsoft-translator → Azure Cognitive Services Translator
  • libretranslate → Self-hosted LibreTranslate (AGPL, free)
  • api → Thin pipe to any remote REST endpoint

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 champollion. It's a separate tool that produces static output (JSON files). Champollion just reads those files.

→ Eval Harness on GitHub

Champollion 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 → champollion (one-way export)​

Contract: Plugin Specification

Champollion Translate → champollion (API at runtime)​

Champollion'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 champollion?Knows about Champollion Translate?Knows about harness?
champollion(is champollion)Yes — api method calls itNo — just reads plugin exports
Champollion TranslateYes — serves its requests(is Champollion 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 champollion sync

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

Scenario 2: Google Translate baseline​

export GOOGLE_TRANSLATE_API_KEY=AIza...
npx champollion sync

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

Scenario 3: Open plugin with bundled coaching​

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

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

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

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

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

Language Cards​

Each language in champollion is configured through a Language Card — a unified JSON file containing register presets, formality rules, method support flags, typography conventions, genealogical classification, and linguistic reference data.

Cards are loaded eagerly at import. Each card contains all metadata the translation engine and developer docs need — there is no separate reference tier. Cards are generated from authoritative sources (IANA, CLDR, Glottolog, WALS) using scripts/generate-language-card.mjs and scripts/build-language-tree.mjs, then human-curated for linguistic accuracy.

Design Principles​

  1. No circular dependencies. The bridges are one-way.
  2. Champollion 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. Champollion Translate → host methods. Champollion → translate files.

See Also​