Zum Hauptinhalt springen

Tutorial: Erstellen eines Übersetzungs-Plugins

Erstellen Sie eine benutzerdefinierte Übersetzungsmethode von Grund auf, führen Sie ein Benchmarking durch und stellen Sie sie als champollion-Plugin bereit. Dies ist der vollständige Arbeitsablauf zum Hinzufügen eines neuen Sprachpaares, das von keiner gebrauchsfertigen API unterstützt wird.

Was Sie erstellen werden: Ein gecoachtes Übersetzungs-Plugin für formales Französisch mit erzwungener Terminologie, Grammatikregeln und Benchmark-Werten.

Zeitaufwand: 30–45 Minuten

Voraussetzungen:

  • champollion installiert (npm install --save-dev champollion)
  • Ein OpenRouter-API-Schlüssel (OPENROUTER_API_KEY)
  • Python 3.10+ (für das Eval-Harness)

Schritt 1: Das Problem identifizieren​

Sie übersetzen ein SaaS-Dashboard ins Französische. Die Standardmethode llm erzeugt korrekte, aber inkonsistente Übersetzungen:

  • Manchmal wird aus „dashboard" „tableau de bord", manchmal „panneau de contrôle"
  • Der Tonfall wechselt zwischen tu- und vous-Formen
  • Fachbegriffe werden inkonsistent anglisiert

Sie benötigen Terminologie-Erzwingung und Register-Steuerung, die der generische LLM-Prompt nicht bietet.

Schritt 2: Coaching-Daten erstellen​

Erstellen Sie eine Coaching-Datei, die Ihre sprachlichen Anforderungen kodiert:

mkdir -p .champollion/coaching
.champollion/coaching/fr.json
{
  "grammar_rules": [
    "Always use the 'vous' form for formal register",
    "French adjectives agree in gender and number with their noun",
    "Use the present tense for UI instructions, not the imperative",
    "Preserve sentence-final punctuation style from the source"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres",
    "environment variable": "variable d'environnement",
    "webhook": "webhook",
    "API key": "clé API",
    "sign in": "se connecter",
    "sign out": "se déconnecter",
    "repository": "dépôt",
    "pull request": "demande de tirage"
  },
  "style_notes": "Formal technical French. Prefer native French terms over anglicisms where established equivalents exist. Keep UI labels concise — 3 words maximum where possible."
}

Was jedes Feld bewirkt:

  • grammar_rules — Wird als explizite Einschränkungen in den LLM-System-Prompt injiziert
  • dictionary — Wird mit Quellschlüsseln abgeglichen; wenn ein Wörterbuchbegriff erscheint, wird er als „erforderliche Terminologie" in den Prompt injiziert
  • style_notes — Wird als allgemeine Stilrichtlinie an den System-Prompt angehängt

Schritt 3: Das Sprachpaar konfigurieren​

Weisen Sie champollion an, llm-coached für Französisch zu verwenden:

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "pairs": {
    "en:fr": {
      "method": "llm-coached",
      "model": "google/gemini-3.5-flash",
      "temperature": 0.2
    }
  },
  "languages": {
    "fr": {
      "register": "Formal technical French (vous-form)",
      "name": "French"
    }
  }
}

Schritt 4: Testen​

npx champollion sync --dry

Überprüfen Sie die Ausgabe des Probelaufs. Stellen Sie sicher, dass:

  • ✅ Wörterbuchbegriffe konsistent verwendet werden („tableau de bord", nicht „panneau de contrôle")
  • ✅ Durchgängig die vous-Form verwendet wird
  • ✅ Fachbegriffe mit Ihrem Wörterbuch übereinstimmen

Führen Sie anschließend die tatsächliche Synchronisierung durch:

npx champollion sync

Schritt 5: Benchmarking mit dem Eval-Harness (Optional)​

Wenn Sie Qualitätswerte wünschen — und das tun Sie, denn Plugins werden mit Benchmark-Daten ausgeliefert — verwenden Sie das begleitende Eval-Harness.

Das Harness installieren​

pip install mt-eval-harness

Einen Referenzkorpus erstellen​

Erstellen Sie eine Datei mit Quellzeichenketten und als korrekt bekannten Übersetzungen:

corpus/french-formal.json
[
  {
    "source": "Dashboard",
    "reference": "Tableau de bord"
  },
  {
    "source": "Sign in to your account",
    "reference": "Connectez-vous à votre compte"
  },
  {
    "source": "Your deployment is ready",
    "reference": "Votre déploiement est prêt"
  },
  {
    "source": "Environment variables",
    "reference": "Variables d'environnement"
  }
]

Das Benchmark ausführen​

mt-eval test \
  --corpus corpus/french-formal.json \
  --source en \
  --target fr \
  --model google/gemini-3.5-flash \
  --temperature 0.2 \
  --champollion-config champollion.config.json

Das Harness gibt Folgendes aus:

  • chrF++ — F-Wert auf Zeichenebene (0–100). Über 70 ist stark.
  • BLEU — N-Gramm-Überlappung (0–100). Über 40 ist solide für gecoachte Übersetzung.
  • Exakte Übereinstimmungsrate — Anteil der Übersetzungen, die exakt mit der Referenz übereinstimmen.
  • COMET — Neuronale Qualitätsmetrik (sofern über mt-eval setup --comet installiert).

:::tip Testen Sie, was Sie ausliefern Die Verwendung von --champollion-config importiert Ihr Produktionsmodell, Register, Temperatur und Coaching-Daten direkt aus Ihrer champollion.config.json. Dies stellt sicher, dass Sie genau die Methode benchmarken, die Sie bereitstellen werden. :::

Das Plugin exportieren​

Sobald Sie mit den Werten zufrieden sind:

mt-eval export \
  --name french-formal-v1 \
  --report eval/logs/harness/run_report.json \
  --output ./french-formal-v1/

Dies erstellt:

french-formal-v1/
├── method.json          # Manifest with config + benchmarks
└── coaching/
    └── fr.json          # Your coaching data

Schritt 6: Das Plugin in Champollion installieren​

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

Dadurch wird das Plugin nach .champollion/methods/french-formal-v1/ kopiert.

Aktualisieren Sie Ihre Konfiguration, um es zu verwenden:

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

Schritt 7: Überprüfen​

# Check plugin is installed and shows benchmark scores
npx champollion status

# Run a sync with the plugin
npx champollion sync

# Audit licensing status
npx champollion provenance

Die Ausgabe von status zeigt Folgendes:

en → fr
  Method:    french-formal-v1 (llm-coached)
  Model:     google/gemini-3.5-flash
  Quality:   high
  chrF++:    74.2
  BLEU:      46.8
  Exact:     42%

Was Sie erstellt haben​

Sie verfügen nun über:

  1. Coaching-Daten — Grammatikregeln und Terminologie, die Konsistenz erzwingen
  2. Benchmark-Werte — Quantifizierte Qualität, die mit dem Plugin ausgeliefert wird
  3. Ein portables Plugin — method.json + Coaching-Daten, auf jedem Rechner installierbar
  4. Produktionsbereitstellung — Integriert in Ihre Synchronisierungs-Pipeline

Nächste Schritte​