Konfiguration

Champollion funktioniert ohne Konfiguration — es erkennt Locale-Dateien, Format und Zielsprachen automatisch in Ihrem Projekt. Für mehr Kontrolle erstellen Sie champollion.config.json im Stammverzeichnis Ihres Projekts oder führen Sie aus:

npx champollion init

Vollständige Konfigurationsreferenz

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "temperature": 0.3,
  "defaultMethod": "llm",
  "batchSize": 80,
  "coachingFile": null,
  "promptContext": null,
  "jsonConcurrency": 200,
  "contentConcurrency": 48,
  "fallbackPrefix": "[EN] ",
  "apiKeyEnvVar": "OPENROUTER_API_KEY",
  "baseUrl": "",
  "pairs": {},
  "languages": {},
  "lint": {
    "srcDir": null,
    "ignore": ["node_modules", ".next", "dist"],
    "minLength": 2
  },
  "seo": {
    "urlPattern": "/:locale/:path",
    "pages": null
  },
  "typegen": {
    "output": null,
    "autoGenerate": false
  }
}

:::note typegen ist noch nicht implementiert Der Konfigurationsblock typegen wird vom Konfigurationslader erkannt und beibehalten, aber die TypeScript-Typgenerierung ist noch nicht implementiert. Dies ist ein Platzhalter für eine geplante Funktion. Das Setzen dieser Werte hat keine Auswirkung. :::

Felder

Feld	Typ	Standard	Beschreibung
`version`	`number`	`3`	Version des Konfigurationsschemas. Immer `3`.
`inputLocale`	`string`	`"en"`	Quellsprachcode (BCP 47).
`localesDir`	`string`	`"./locales"`	Pfad zu den Locale-Dateien. Champollion durchsucht dieses Verzeichnis.
`contentDir`	`string`	`null`	Hugo-Inhaltsverzeichnis. Aktiviert die Übersetzung des Markdown-Inhalts.
`translatableFields`	`string[]`	`null`	Überschreibt die standardmäßig übersetzbaren Frontmatter-Felder für die Inhaltsübersetzung. `null` verwendet die integrierten Standardwerte (`title`, `description`, `summary`).
`format`	`string`	`"auto"`	Dateiformat: `json`, `toml`, `yaml` oder `auto` (Erkennung anhand der Erweiterung).
`model`	`string`	`"google/gemini-3.5-flash"`	Standardmodell für LLM-Methoden. Akzeptiert vollständige OpenRouter-Slugs (`provider/model`) oder Kurzaliasse aus `shared/model-aliases.json` (z. B. `gemini-flash`). Direkte Anbieter verwenden reine Namen (z. B. `gpt-4o`).
`temperature`	`number`	`0.3`	LLM-Temperatur (0.0–2.0). Niedriger = deterministischer.
`defaultMethod`	`string`	`"llm"`	Standardübersetzungsmethode: `llm`, `llm-coached`, `google-translate`, `deepl`, `microsoft-translator`, `libretranslate`, `openai`, `anthropic`, `gemini`, `api`. Wird durch das CLI-Flag `--method` überschrieben.
`batchSize`	`number`	`80`	Schlüssel pro Übersetzungsstapel. Höher = weniger API-Aufrufe, aber größere Prompts.
`coachingFile`	`string`	`null`	Pfad zu einer Freitext-Coaching-Prompt-Datei (relativ zum Projektstammverzeichnis). Der Inhalt wird beim Start gelesen und als `Coaching guidance:`-Block in den System-Prompt eingefügt.
`promptContext`	`string`	`null`	Anwendungskontext-Zeichenfolge, die in den System-Prompt eingefügt wird (z. B. „E-Commerce-Produktbeschreibungen"). Hilft dem Modell, Übersetzungen auf Ihren Fachbereich abzustimmen.
`jsonConcurrency`	`number`	`200`	Maximale parallele Locale-Übersetzungen für die JSON-Schlüsselsynchronisation. Wird durch das CLI-Flag `--json-concurrency` überschrieben.
`contentConcurrency`	`number`	`48`	Maximale parallele API-Aufrufe für die Inhaltsübersetzung (Markdown/MDX). Wird durch das CLI-Flag `--content-concurrency` überschrieben.
`fallbackPrefix`	`string`	`"[EN] "`	Markierungspräfix, das von `audit` und `verify` verwendet wird, um veraltete, nicht übersetzte Werte aus früheren Durchläufen zu erkennen. Champollion schreibt dieses Präfix nicht — es wird nur zur Erkennung gelesen.
`apiKeyEnvVar`	`string`	`"OPENROUTER_API_KEY"`	Name der Umgebungsvariable für den API-Schlüssel. Überschreiben für benutzerdefinierte Umgebungsvariablennamen.
`baseUrl`	`string`	`""`	Basis-URL für die Generierung von SEO-Artefakten (hreflang, Sitemaps, JSON-LD).
`pairs`	`object`	`{}`	Überschreibungen für Methode, Modell und Qualität pro Paar. Siehe Paarkonfiguration.
`languages`	`object`	`{}`	Überschreibungen pro Sprache. Siehe Sprachkonfiguration.
`lint.srcDir`	`string`	`null`	Quellverzeichnis für das Lint-Scanning. `null` = automatische Erkennung anhand des Frameworks.
`lint.ignore`	`string[]`	`["node_modules", ...]`	Glob-Muster, die vom Linting ausgeschlossen werden sollen.
`lint.minLength`	`number`	`2`	Minimale Zeichenfolgenlänge, um sie als fest codiert zu kennzeichnen.
`seo.urlPattern`	`string`	`"/:locale/:path"`	URL-Mustervorlage für die Generierung von hreflang-Tags.
`seo.pages`	`string[]`	`null`	Explizite Seitenliste für SEO. `null` = automatische Erkennung anhand der Locale-Schlüssel.
`typegen.output`	`string`	`null`	Ausgabepfad für generierte TypeScript-Typen. `null` = deaktiviert.
`typegen.autoGenerate`	`boolean`	`false`	Typen nach jeder Synchronisation automatisch neu generieren.

Paarkonfiguration

Jedes Quell→Ziel-Paar kann unabhängig konfiguriert werden:

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

Paarfelder

Feld	Typ	Beschreibung
`method`	`string`	Übersetzungsmethode: `llm`, `llm-coached`, `google-translate`, `deepl`, `microsoft-translator`, `libretranslate`, `openai`, `anthropic`, `gemini`, `api`
`methodPlugin`	`string`	Name eines installierten Plugins (aus `.champollion/methods/`)
`model`	`string`	Überschreibt das Standardmodell für dieses Paar
`temperature`	`number`	Überschreibt die Standardtemperatur für dieses Paar
`batchSize`	`number`	Überschreibt die Standard-Stapelgröße für dieses Paar
`register`	`string`	Register-/Tonalitätsüberschreibung (Preset-Schlüssel oder Freitext)
`endpoint`	`string`	URL des Remote-API-Endpunkts. Erforderlich, wenn `method` `api` ist.
`coachingFile`	`string`	Pfad zu einer Coaching-Prompt-Datei für dieses Paar
`promptContext`	`string`	Anwendungskontext für dieses Paar
`qualityTier`	`string`	Anzeigestufe: `standard`, `high`, `research`, `verified`

Sprachkonfiguration

Sprachen akzeptieren drei Formate:

Array von Codes (am einfachsten)

{
  "languages": ["fr", "de", "ja"]
}

Jede Sprache erhält ihr Standardregister aus der integrierten Registertabelle. Sprachen ohne Standard erhalten "Professional register.".

Objekt mit Register-Zeichenfolgen

Der Wert kann ein Preset-Schlüssel aus der Sprachkarte oder ein benutzerdefinierter Registertext sein:

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

Champollion prüft, ob die Zeichenfolge mit einem Preset-Schlüssel in der Sprachkarte übereinstimmt. Wenn ja, wird der vollständige Register-Prompt aus der Karte verwendet. Wenn nicht, wird die Zeichenfolge unverändert verwendet. Siehe Unterstützte Sprachen für verfügbare Presets.

Objekt mit vollständiger Konfiguration

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

Sie können Kurzformen und vollständige Objekte im selben Block mischen.

Sprachfelder

Feld	Typ	Beschreibung
`register`	`string`	Stil-/Tonalitätsanweisungen. Kann ein Preset-Schlüssel (z. B. `casual-tu`, `formal-hapsyo`) oder benutzerdefinierter Text sein. Siehe Sprachkarten.
`name`	`string`	Menschenlesbarer Sprachname (für die Statusanzeige)
`model`	`string`	Überschreibt das Standardmodell
`temperature`	`number`	Überschreibt die Standardtemperatur
`batchSize`	`number`	Überschreibt die Standard-Stapelgröße
`coachingFile`	`string`	Pfad zu einer Coaching-Prompt-Datei für diese Sprache
`promptContext`	`string`	Anwendungskontext für diese Sprache
`maxRetries`	`number`	Maximales Wiederholungsbudget für fehlgeschlagene Stapel (Standard: 3)
`script`	`string`	ISO-15924-Schriftcode. Löst die Schriftvalidierung im Quality Gate aus.

:::info Vererbungskette Einstellungen werden in dieser Reihenfolge aufgelöst (das erste gewinnt):

Paarebene → Sprachebene → globale Konfiguration → Standardwerte

Wenn beispielsweise pairs["en:fr"] model setzt, überschreibt es sowohl die Werte model auf Sprachebene als auch die globalen. :::

Nicht-englische Quelle

Wenn Ihre Quellsprache nicht Englisch ist:

# CLI flag (one-time)
npx champollion sync --source fr

champollion.config.json (permanent)
{
  "inputLocale": "fr"
}

Lock-Datei

Champollion erstellt .champollion.lock, um SHA-256-Hashes der übersetzten Quellwerte zu verfolgen. Committen Sie diese Datei, damit alle Entwickler dieselbe Übersetzungsbasis teilen.

Wenn sich ein Quellwert ändert, stimmt der Hash nicht mehr überein, und champollion übersetzt diesen Schlüssel bei der nächsten Synchronisation erneut.

`.champollionignore`

Erstellen Sie .champollionignore im Stammverzeichnis Ihres Projekts, um Dateien vom lint-Scanning auszuschließen. Verwendet Glob-Muster, wie .gitignore:

.champollionignore
src/components/legacy/**
src/utils/constants.js
**/*.test.js

Verzeichnis `.champollion/`

Champollion erstellt ein .champollion/-Verzeichnis im Stammverzeichnis Ihres Projekts für den internen Zustand. Sie sollten dies in der Regel zu .gitignore hinzufügen — es handelt sich um lokale Optimierung, nicht um Projektquellcode:

.champollion/

Datei	Zweck	Committen?
`tm.json`	Translation-Memory-Cache — speichert frühere Übersetzungen, indexiert nach Quelltext + Locale + Methode	Nein (lokaler Cache)
`xliff/*.xliff`	XLIFF-Exportdateien zur Überprüfung durch professionelle Übersetzer	Nein (vorübergehend)
`methods/`	Manifeste installierter Methoden-Plugins	Ja (gemeinsame Konfiguration)
`backups/`	Pre-Wrap-Sicherungen (erstellt von `wrap --undo`)	Nein (Sicherheitsnetz)

Siehe Translation Memory für Details zu tm.json und wie es API-Kosten spart.

Programmatische API

Für Build-Skripte und benutzerdefinierte Integrationen importieren Sie direkt aus dem Paket:

import { GeminiMethod, runSync, resolveConfig } from 'champollion';

// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
  ['greeting', 'farewell'],
  { greeting: 'Hello', farewell: 'Goodbye' },
  { target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
  { cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }

Verfügbare Exporte

Export	Funktion
`TranslationMethod`	Basisklasse für alle Methoden
`LLMMethod`	Basisklasse für LLM-Methoden (OpenRouter)
`DirectLLMMethod`	Basisklasse für direkte LLM-Anbieter (OpenAI, Anthropic, Gemini)
`OpenAIMethod`, `AnthropicMethod`, `GeminiMethod`	Direkte LLM-Anbieterklassen
`DeepLMethod`, `MicrosoftTranslatorMethod`, `LibreTranslateMethod`	Traditionelle MT-Klassen
`GoogleTranslateMethod`	Google Cloud Translation
`LLMCoachedMethod`	Gecoachtes LLM (OpenRouter + Coaching-Daten)
`APIMethod`	Remote-API-Client
`runSync`, `runContentSync`	Vollständige Synchronisationspipeline
`resolveConfig`, `resolvePairs`	Konfigurationsauflösung
`validateTranslations`	Quality Gate
`loadCoachingData`, `findDictionaryMatches`	Coaching-Hilfsprogramme

Erweiterung für benutzerdefinierte Anbieter

Erweitern Sie DirectLLMMethod, um einen neuen LLM-Anbieter in ~40 Zeilen hinzuzufügen:

import { DirectLLMMethod } from 'champollion';

class MistralMethod extends DirectLLMMethod {
  constructor(options) {
    super(options);
    this.name = 'mistral';
  }
  _getApiKeyEnvVar()     { return 'MISTRAL_API_KEY'; }
  _getApiKeyOptionsKey() { return 'mistralApiKey'; }
  _getDefaultModel()     { return 'mistral-large-latest'; }
  _getProviderLabel()    { return 'Mistral'; }

  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
    return {
      url: 'https://api.mistral.ai/v1/chat/completions',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: {
        model,
        messages: [
          ...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
          { role: 'user', content: prompt },
        ],
        temperature,
      },
    };
  }

  _extractResponseText(json) {
    return json.choices?.[0]?.message?.content;
  }

  // Optional but recommended: provider-specific setup help when translation fails
  getSetupHelp() {
    if (!process.env.MISTRAL_API_KEY) {
      return [
        '',
        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
        '  │ Mistral requires an API key from https://console.mistral.ai   │',
        '  │ Run: export MISTRAL_API_KEY=...                               │',
        '  └────────────────────────────────────────────────────────────────┘',
      ];
    }
    return ['        API key is set but translation failed. Check your Mistral dashboard.'];
  }
}

Sie erhalten Übersetzung, Coaching, Wiederholungsschleifen, Modellvalidierung, Qualitätsstufen und Einrichtungshilfe kostenlos. Nur die Form der HTTP-Anfrage ist anbieterspezifisch. Für Nicht-LLM-Adapter, die rohes fetch() verwenden, nutzen Sie das gemeinsame fetchWithRetry()-Hilfsprogramm aus lib/methods/fetch-with-retry.js, anstatt Ihre eigene Wiederholungsschleife zu schreiben.

Siehe auch

CLI-Referenz — alle Befehle und Flags
Übersetzungsmethoden — Auswahl und Kombination von Methoden
Translation Memory — Caching und Kosteneinsparungen
Arbeiten mit professionellen Übersetzern — XLIFF-Workflow
Plugin-Spezifikation — Manifestformat für Methoden-Plugins
Architektur — wie die Teile zusammenhängen
Unterstützte Sprachen — integrierte Sprachunterstützung
Wie die Synchronisation funktioniert — die Übersetzungspipeline

Vollständige Konfigurationsreferenz​

Felder​

Paarkonfiguration​

Paarfelder​

Sprachkonfiguration​

Array von Codes (am einfachsten)​

Objekt mit Register-Zeichenfolgen​

Objekt mit vollständiger Konfiguration​

Sprachfelder​

Nicht-englische Quelle​

Lock-Datei​

.champollionignore​

Verzeichnis .champollion/​

Programmatische API​

Verfügbare Exporte​

Erweiterung für benutzerdefinierte Anbieter​

Siehe auch​