Agent-Leitfaden: Verwendung von champollion

champollion ist ein CLI-Tool, das die Locale-Dateien Ihrer App mit einem einzigen Befehl übersetzt. Dieser Leitfaden richtet sich an KI-Agenten (oder Entwickler, die mit KI-Agenten arbeiten), die schnell von null zu übersetzten Locale-Dateien gelangen möchten.

:::tip Bereits vertraut? Wenn Sie nur die Befehle benötigen, springen Sie zur CLI-Referenz. Wenn Sie eine Übersetzungsmethode erstellen und benchmarken möchten, siehe den Arena Agent Guide. :::

Einrichtung der Umgebung

# No global install needed — npx runs it directly
npx champollion sync

Voraussetzungen:

Node.js 18+
Ein API-Schlüssel für Ihren Übersetzungsanbieter

Einrichtung des API-Schlüssels — champollion benötigt mindestens einen Schlüssel, abhängig davon, welche Methoden Sie verwenden:

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Champollion liest .env automatisch. Holen Sie sich einen OpenRouter-Schlüssel unter openrouter.ai/keys.

Erste Synchronisierung

Champollion erkennt automatisch Ihre Locale-Dateien, deren Format (JSON, TOML, YAML, PO) und Ihre Zielsprachen:

npx champollion sync

Was passiert:

Lädt champollion.config.json (oder erkennt die Einstellungen automatisch)
Scannt Ihre Quell-Locale-Datei, flacht verschachtelte Schlüssel ab
Vergleicht mit .champollion.lock (SHA-256-Hashes zuvor übersetzter Werte)
Prüft .champollion/tm.json auf zwischengespeicherte Übersetzungen (Translation Memory)
Übersetzt nur geänderte, fehlende oder veraltete Schlüssel über die konfigurierte Methode
Führt das Quality Gate (5 Prüfungen) bei jeder Übersetzung aus
Schreibt bestandene Übersetzungen in die Ziel-Locale-Datei
Aktualisiert die Lock-Datei und den TM-Cache

Bei einer typischen erneuten Ausführung nach Änderung eines Schlüssels liefert Schritt 4 142 Schlüssel aus dem Cache und Schritt 5 übersetzt 1 Schlüssel. Aus diesem Grund sind nachfolgende Synchronisierungen schnell und kostengünstig.

Konfiguration

Erstellen Sie champollion.config.json im Stammverzeichnis Ihres Projekts:

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

Wichtige Felder:

Feld	Zweck	Standard
`inputLocale`	Quellsprache	`en`
`pairs`	Zuordnung Quelle→Ziel mit Methodenkonfiguration	(erforderlich)
`localesDir`	Wo sich die Locale-Dateien befinden	(automatisch erkannt)
`model`	LLM-Modell für `llm`/`llm-coached`-Methoden	`google/gemini-2.5-flash`
`batchSize`	Schlüssel pro API-Aufruf	80 (LLM), 128 (Google)
`jsonConcurrency`	Parallele Locale-Übersetzungen für JSON-Schlüssel	200
`contentConcurrency`	Parallele API-Aufrufe für die Inhaltsübersetzung	48

Vollständige Referenz: Konfiguration

Übersetzungsmethoden

Methode	Wann zu verwenden	Kosten	Benötigter API-Schlüssel
`llm`	Allzweck, gut geeignet für gut ausgestattete Sprachen	Pro Token (modellabhängig)	`OPENROUTER_API_KEY`
`llm-coached`	Wenn Sie Grammatikregeln/ein Wörterbuch für die Zielsprache haben	Pro Token + Coaching-Kontext	`OPENROUTER_API_KEY`
`google-translate`	Ressourcenstarke Sprachen, bei denen GT gut funktioniert	20 $/Million Zeichen	`GOOGLE_TRANSLATE_API_KEY`
`api`	Benutzerdefinierte Pipeline hinter einem HTTP-Endpunkt gehostet	Serverbestimmt	Keiner (Endpunkt übernimmt Authentifizierung)
`plugin`	Vorgefertigte Methode, lokal installiert	Variiert	Variiert

Details: Übersetzungsmethoden

Coaching-Daten

Für llm-coached-Paare steuern Coaching-Daten das LLM mit explizitem linguistischem Wissen. Erstellen Sie eine Coaching-Datei:

coaching/fr.json
{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

Verweisen Sie in Ihrer Paar-Konfiguration darauf:

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

Das Quality Gate überprüft, ob Wörterbuchbegriffe tatsächlich in der Ausgabe erscheinen — Verstöße werden als [TERM]-Warnungen protokolliert.

Details: Coaching-Daten

Quality Gate

Jede Übersetzung durchläuft fünf automatisierte Prüfungen, bevor sie auf die Festplatte geschrieben wird:

Prüfung	Was sie erkennt	Beispiel
Leer/leerer Inhalt	Modell hat nichts zurückgegeben	`""`
Quell-Echo	Modell hat die englische Eingabe unverändert zurückgegeben	`"Welcome"` für Japanisch
Halluzinationsschleife	Wiederholte Trigramme	`"Qo' Qo' Qo' Qo'"`
Längeninflation	Ausgabe ist 4-fach+ länger als die Quelle	10-Zeichen-Quelle → 50-Zeichen-Ausgabe
Skriptkonformität	Falsches Skript für die Locale	Lateinischer Text für arabische Locale

Fehler werden mit dem Präfix [GATE] protokolliert. Keine stillen Fallbacks — wenn eine Übersetzung fehlschlägt, wird sie gemeldet, nicht stillschweigend akzeptiert.

Details: Quality Gate

Translation Memory

Champollion speichert Übersetzungen in .champollion/tm.json zwischen, indiziert nach Quelltext + Locale + Methode. Bei nachfolgenden Synchronisierungen werden unveränderte Schlüssel aus dem Cache bereitgestellt — kein API-Aufruf, keine Kosten.

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

Um den Cache für einen Durchlauf zu umgehen: npx champollion sync --no-tm

Details: Translation Memory

Generierte Dateien

Champollion erstellt mehrere Dateien in Ihrem Projekt. Machen Sie sich damit vertraut, damit Sie nicht versehentlich die falschen löschen oder committen:

Datei	Zweck	Git?
`.champollion.lock`	SHA-256-Hashes übersetzter Quellwerte (Änderungserkennung)	Ja — committen Sie diese
`.champollion-content.lock`	Dasselbe, aber für Markdown-/MDX-Inhaltsdateien	Ja — committen Sie diese
`.champollion/tm.json`	Translation-Memory-Cache	Ja — committen Sie diese (spart API-Kosten für das Team)
`.champollion/coaching/`	Verzeichnis für Coaching-Daten	Ja — dies ist Ihr linguistisches Wissen
`champollion.config.json`	Projektkonfiguration	Ja — committen Sie diese

Häufige Muster

Ein Sprachpaar übersetzen:

npx champollion sync --pair en-fr

Alle konfigurierten Paare übersetzen:

npx champollion sync

Champollion übersetzt alle Locales parallel. Mit TM-Caching erreichen nur geänderte Schlüssel die API.

Inhaltsmodus (Markdown/MDX für Docusaurus, Hugo usw.):

npx champollion sync --content

Übersetzt Dokumentationen, Blog-Beiträge und Inhaltsdateien zusammen mit der Locale-JSON. Verwendet parallele Nebenläufigkeit (Standard: 48 gleichzeitige API-Aufrufe). Anpassbar mit --content-concurrency.

Probelauf (Vorschau ohne Schreiben):

npx champollion sync --dry-run

Erneute Übersetzung bestimmter Schlüssel erzwingen:

npx champollion sync --force-keys "hero.title,nav.about"

Erneute Übersetzung aller Inhaltsdateien erzwingen:

npx champollion sync --force-content

Übersetzungsstatus prüfen:

npx champollion status

Zeigt Abdeckung, Qualitätsstufen und Plugin-Informationen für jedes Paar an.

Auf nicht übersetzte Fallbacks prüfen:

npx champollion audit

Listet alle [EN]-Fallback-Werte auf, die übersetzt werden müssen.

Fehlerbehebung

Problem	Lösung
`OPENROUTER_API_KEY not set`	Exportieren Sie den Schlüssel oder fügen Sie ihn zu `.env` im Stammverzeichnis Ihres Projekts hinzu
`No locale files found`	Setzen Sie `localesDir` in der Konfiguration oder stellen Sie sicher, dass Ihre Locale-Dateien der Standardbenennung entsprechen (`en.json`, `fr.json`)
`[GATE] Script compliance failed`	Ihre Ziel-Locale hat lateinischen Text statt des erwarteten Skripts erhalten — versuchen Sie ein anderes Modell oder fügen Sie Coaching-Daten hinzu
`[GATE] Source echo`	Das Modell hat unverändertes Englisch zurückgegeben — Coaching-Daten oder ein anderes Modell beheben dies in der Regel
Alle Übersetzungen zwischengespeichert	Führen Sie es mit `--no-tm` aus, um den Cache zu umgehen, oder mit `--force-keys` für bestimmte Schlüssel
Konflikte in der Lock-Datei	`.champollion.lock` verwendet SHA-256-Hashes — Merge-Konflikte können sicher gelöst werden, indem Sie eine der beiden Versionen behalten und dann die Synchronisierung erneut ausführen

Wie geht es weiter

Schnellstart — vollständige Einführungsanleitung
CLI-Referenz — jeder Befehl und jedes Flag
Funktionsweise — die Synchronisierungs-Pipeline erklärt
The Eval Harness Bridge — wie champollion mit der Arena verbunden wird
Möchten Sie Ihre eigene Übersetzungsmethode erstellen? Siehe den Arena Agent Guide — erstellen Sie eine Methode, beweisen Sie, dass sie funktioniert, und gewinnen Sie Preise.

Einrichtung der Umgebung​

Erste Synchronisierung​

Konfiguration​

Übersetzungsmethoden​

Coaching-Daten​

Quality Gate​

Translation Memory​

Generierte Dateien​

Häufige Muster​

Fehlerbehebung​

Wie geht es weiter​