Zum Hauptinhalt springen

CLI-Referenz

Befehle​

champollion init              Interactive setup wizard (--yes for quick defaults)
champollion sync              Translate & sync all locale files
champollion watch             Auto-sync when the source file changes
champollion audit             List all untranslated [EN] fallback values
champollion lint              Scan source code for hardcoded strings
champollion wrap              Auto-wrap hardcoded strings in t() calls (with undo)
champollion seo <sub>         Generate hreflang, sitemap.xml, or JSON-LD schema
champollion integrity         Audit locale files for format/encoding issues
champollion verify            Verify translations are present and correct (CI gate)
champollion status            Show pair configuration, plugins, and quality tiers
champollion provenance        Audit translation resource licensing
champollion plugin <sub>      Manage method plugins (install, remove, list)
champollion fonts <sub>       Download web fonts for PUA script converters
champollion leaderboard      Browse and install methods from the MT Eval Arena leaderboard
champollion tm <sub>          Manage Translation Memory cache (stats, clear)
champollion xliff <sub>       Export/import XLIFF 1.2 for professional review

Führen Sie champollion <command> --help aus, um detaillierte Hilfe zu einem beliebigen Befehl zu erhalten.

Globale Optionen​

--help, -h              Show help (global or per-command)
--version, -v           Print version and exit
--yes, -y               Skip interactive prompts, use defaults
--config <path>         Custom config file path
--dir <path>            Override locales directory
--content-dir <path>    Hugo/Docusaurus content directory for Markdown translation
--source <code>         Override source locale (default: en)
--model <model>         Override translation model (full slug or alias from shared/model-aliases.json)
--method <method>       Translation method: llm, google-translate (default: from config)
--temperature <n>       LLM temperature (0.0–2.0, default: 0.3)
--coaching-file <path>  Path to free-text coaching prompt file (injected into system prompt)
--format <fmt>          Locale file format: json, toml, yaml, or auto
--dry, --dry-run        Preview changes without writing files
--concurrency <n>       Max parallel API calls (sets both JSON and content, default: 48)
--json-concurrency <n>  Max parallel locale translations for JSON keys (default: 200)
--content-concurrency <n> Max parallel API calls for content translation (default: 48)
--force-content         Re-translate all content files (clears content lock)
--force-keys <keys>     Comma-separated dot-notation keys to force re-translate
--no-tm                 Skip Translation Memory cache for this sync run
--no-verify             Skip post-sync verification pass
--locale <code>         Target locale (xliff export, tm clear)
--quiet                 Errors and warnings only — suppress banner, progress bar, and info lines
--json                  Machine-readable NDJSON output — one JSON object per event

init​

Interaktiver Einrichtungsassistent, der champollion.config.json erstellt. Führt durch Quell-Locale, Zielsprachen, Dateiformat und Übersetzungsmodell.

champollion init                          # interactive wizard
champollion init --yes                    # skip wizard, use defaults
champollion init --yes --langs fr,de,ja   # quick setup with specific languages
champollion init --source en --dir ./i18n # overrides with defaults

--langs-Option: Durch Kommas getrennte Liste von Zielsprachcodes. Überspringt die Sprachabfrage und wendet die Standard-Register-Voreinstellungen für jede Sprache an. Kombinieren Sie sie mit --yes für eine vollständig nicht-interaktive Einrichtung.

Sprach-Voreinstellungen: Wenn Sie zur Eingabe von Zielsprachen aufgefordert werden, können Sie Voreinstellungsnamen eingeben:

  • european → fr, de, es, it, pt, nl
  • asian → ja, zh, ko
  • global → fr, es, de, ja, zh, ko, pt, ar
  • nordic → da, fi, nb, sv

Mischen Sie Voreinstellungen und einzelne Codes: european, ja → fr, de, es, it, pt, nl, ja

sync​

Übersetzt fehlende und veraltete Schlüssel in allen Locale-Dateien. Führt standardmäßig eine Nach-Sync-Überprüfung durch.

champollion sync                                   # translate everything
champollion sync --dry-run                         # preview only
champollion sync --force-keys "hero.title"         # force re-translate
champollion sync --force-keys "a.title,a.subtitle" # multiple keys
champollion sync --force-content                   # re-translate all Markdown/MDX
champollion sync --content-dir ./content           # include Hugo Markdown
champollion sync --method google-translate          # force Google Translate
champollion sync --concurrency 20                  # 20 parallel API calls (both phases)
champollion sync --json-concurrency 30              # 30 parallel locale translations (JSON)
champollion sync --content-concurrency 8            # 8 parallel content translations
champollion sync --no-verify                        # skip post-sync verification
champollion sync --no-tm                            # skip cache, fresh API calls

Translation Memory: Standardmäßig lädt sync .champollion/tm.json und liefert zwischengespeicherte Übersetzungen für unveränderte Quellwerte. Verwenden Sie --no-tm, um den Cache zu umgehen (nützlich beim Wechsel von Übersetzungsanbietern oder bei der Qualitätsfehlersuche). Siehe Translation Memory.

Änderungserkennung: champollion speichert SHA-256-Hashes in .champollion.lock. Wenn sich Quellwerte ändern, übersetzt der nächste Sync diese Schlüssel automatisch neu. Committen Sie die Lock-Datei, damit alle Entwickler die gleiche Ausgangsbasis verwenden.

Parallelität: Sowohl die Übersetzung von JSON-Schlüsseln als auch die Inhaltsübersetzung laufen parallel. JSON-Locales werden gleichzeitig übersetzt (Standard: 200 gleichzeitige Locales), wobei auch die Batches innerhalb jeder Locale parallelisiert werden (4 gleichzeitige Batches). Die Inhaltsübersetzung (Markdown, MDX, Blogbeiträge) läuft in einem flachen Arbeitselemente-Pool (Standard: 48 gleichzeitige API-Aufrufe). Überschreiben Sie dies mit --json-concurrency, --content-concurrency oder --concurrency (setzt beide).

Ausgabe: Sync zeigt ein Versionsbanner, Format-/Framework-Erkennung, eine Kostenschätzung und Fortschrittsbalken pro Locale an:

champollion v0.1.0

[INFO] Detected format: json (auto)
[INFO] Source: en.json (2,847 keys)
[INFO] Pairs: es-MX:llm, fr:deepl

[INFO] es-MX.json — 2,847 missing
     ████████████████████████████████ 2,847/2,847 keys
[INFO] fr.json — 2,847 missing
     ████████████████████████████████ 2,847/2,847 keys
[OK] Synced 5,694 keys total.

Die Fortschrittsbalken werden nach jedem Batch (~80 Schlüssel) direkt aktualisiert. Verwenden Sie --quiet für ausschließlich Fehler/Warnungen oder --json für maschinenlesbare NDJSON-Ausgabe. Beide unterdrücken den Fortschrittsbalken und das Banner.

watch​

Automatische Synchronisierung, wenn sich die Quell-Locale-Datei ändert. Läuft, bis sie mit Ctrl+C unterbrochen wird.

champollion watch

audit​

Listet alle nicht übersetzten [EN]-präfixierten Fallback-Werte aus vorherigen Durchläufen auf. Beendet sich mit Code 1, falls welche gefunden werden — verwenden Sie dies als CI-Gate, um Builds mit unvollständigen Übersetzungen scheitern zu lassen.

champollion audit

verify​

Liest alle Locale-Dateien erneut von der Festplatte und überprüft, ob Übersetzungen tatsächlich vorhanden und korrekt sind. Dies ist dieselbe Überprüfung, die am Ende jedes sync automatisch ausgeführt wird (sofern --no-verify nicht übergeben wird).

champollion verify                    # verify all locale files
champollion verify --warn-only        # non-blocking
champollion verify && echo "All good" # CI gate

Was geprüft wird:

  • Schlüssel-Parität — alle Quellschlüssel in jedem Ziel vorhanden
  • [EN]-Fallback-Markierungen aus vorherigen Durchläufen
  • Leere Übersetzungen
  • Skript-Konformität — nicht-lateinische Locales sollten Nicht-ASCII-Übersetzungen aufweisen
  • Platzhalter-Erhaltung — ICU-Platzhalter stimmen mit der Quelle überein
  • Kodierungsprobleme — BOM-Markierungen, unsichtbare Zeichen
  • Quell-Echos — Werte, die mit der Quelle identisch sind (Warnung)

lint​

Durchsucht den Quellcode nach hartkodierten, für Benutzer sichtbaren Zeichenketten, die i18n-Übersetzungsaufrufe verwenden sollten. Erkennt Ihr Framework automatisch (next-intl, react-i18next, vue-i18n, Hugo).

champollion lint                    # exits 1 if issues found
champollion lint --warn-only        # always exits 0
champollion lint --src ./app        # custom source directory
champollion lint --min-length 4     # minimum string length to flag

Was erkannt wird:

  • Hartkodierte Zeichenketten in JSX-Text, placeholder, alt, aria-label, title
  • Dateien mit für Benutzer sichtbarem Inhalt, aber ohne i18n-Framework-Import
  • Tote Schlüssel — Locale-Schlüssel, auf die keine Quelldatei verweist
  • Abdeckungswert — Prozentsatz der Zeichenketten, die über i18n laufen

Ausschlüsse: Erstellen Sie .champollionignore im Stammverzeichnis Ihres Projekts (Glob-Muster, wie .gitignore).

wrap​

Umschließt automatisch hartkodierte Zeichenketten, die von lint erkannt wurden, in t()-Aufrufen. Erstellt automatische Backups vor der Änderung von Dateien.

champollion wrap                    # auto-wrap with backup
champollion wrap --dry              # preview wrapping changes
champollion wrap --undo             # restore from .champollion-backup/

Sicherheits-Gates:

  1. Git-Clean-Prüfung (im Dry-Run übersprungen)
  2. Automatisches Backup nach .champollion-backup/
  3. Diff-Vorschau vor jedem Dateischreibvorgang
  4. --undo-Unterstützung zur Wiederherstellung aus dem Backup

seo​

Generiert SEO-Artefakte für mehrsprachige Websites.

champollion seo hreflang                                        # print hreflang tags
champollion seo sitemap --base-url https://example.com --out sitemap.xml
champollion seo jsonld --base-url https://example.com           # JSON-LD schema
UnterbefehlAusgabe
hreflang<link rel="alternate" hreflang>-Tags
sitemapMehrsprachige sitemap.xml
jsonldJSON-LD-WebSite-Sprachschema

integrity​

Erkennt Beschädigung und Drift in übersetzten Locale-Dateien.

champollion integrity               # exits 1 if issues found
champollion integrity --warn-only   # non-blocking

Was geprüft wird:

  • Platzhalter-Beschädigung (z. B. {name} in der Quelle vorhanden, aber im Ziel fehlend)
  • Kodierungsprobleme (Mojibake, ungültiges Unicode)
  • Nicht übersetzte Kopien (Zielwert identisch mit der Quelle)
  • Verwaiste Schlüssel (Schlüssel im Ziel, die in der Quelle nicht existieren)
  • Vollständigkeit der ICU-MessageFormat-Pluralkategorien (z. B. benötigt Arabisch 6 Kategorien)

tm​

Verwaltet den Translation-Memory-Cache (.champollion/tm.json). TM speichert vorherige Übersetzungen und liefert sie bei nachfolgenden Syncs, anstatt die API aufzurufen.

champollion tm stats                  # show cache statistics
champollion tm clear                  # clear cache (with confirmation)
champollion tm clear --yes            # clear without confirmation
champollion tm clear --locale fr      # clear only French entries
UnterbefehlAusgabe
statsAnzahl der Einträge, Dateigröße, Aufschlüsselung pro Locale
clearCache-Datei löschen (vollständig oder pro Locale)
OptionWirkung
--locale <code>Nur Einträge für eine Locale löschen
--yesBestätigungsabfrage überspringen

Siehe Translation Memory für Informationen darüber, wie TM funktioniert und wann es zu leeren ist.

xliff​

Exportiert und importiert XLIFF-1.2-Dateien für die professionelle Übersetzerprüfung. XLIFF ist das universelle Austauschformat, das von CAT-Tools wie memoQ, SDL Trados und Phrase unterstützt wird.

champollion xliff export --locale fr                   # export French XLIFF
champollion xliff export --locale ja --out ./review/   # custom output path
champollion xliff import .champollion/xliff/fr.xliff       # import reviewed file
champollion xliff import ./reviewed.xliff --dry        # preview import
UnterbefehlAusgabe
export.xliff aus Quell- + Ziel-Locale-Dateien generieren
importGeprüfte .xliff-Übersetzungen in Locale-Dateien zusammenführen
OptionWirkung
--locale <code>Ziel-Locale für den Export (erforderlich)
--out <path>Benutzerdefinierter Ausgabepfad oder Verzeichnis
--dryImport in der Vorschau anzeigen, ohne zu schreiben

Siehe Working with Professional Translators für den vollständigen Workflow.

status​

Zeigt Paarkonfiguration, installierte Plugins, Qualitätsstufen und Benchmark-Werte an.

champollion status

provenance​

Auditiert die Lizenzierung von Übersetzungsressourcen für alle installierten Plugins.

champollion provenance

plugin​

Verwaltet Plugins für Übersetzungsmethoden. Plugins sind vorgefertigte Übersetzungs-Rezepte, die nach .champollion/methods/ installiert werden.

champollion plugin list                      # show installed plugins
champollion plugin install ./my-method/      # install from local directory
champollion plugin remove crk-coached-v1     # remove a plugin

Siehe Plugin Specification für das Plugin-Manifest-Format.

leaderboard​

Durchsuchen, suchen und installieren Sie Übersetzungsmethoden aus dem MT-Eval-Arena-Leaderboard. Vom Leaderboard installierte Methoden werden mit Benchmark-Werten und der vollständigen kanonischen MethodConfig geliefert — der exakten Konfiguration, die während der Evaluierung verwendet wurde.

champollion leaderboard                          # show leaderboard
champollion leaderboard --pair en:fr             # filter by language pair
champollion leaderboard --install crk-coached-v8 # install a method plugin
champollion leaderboard --install crk-coached-v8 --apply  # install + patch config
OptionWirkung
--pair <code>Leaderboard nach Sprachpaar filtern (z. B. en:fr)
--install <name>Ein Methoden-Plugin aus dem Leaderboard installieren
--applyNach der Installation automatisch methodPlugin zu champollion.config.json hinzufügen

--apply-Workflow: Wenn Sie mit --apply installieren, schreibt champollion das Methoden-Plugin nach .champollion/methods/ und passt Ihre champollion.config.json an, um es für das entsprechende Paar zu verwenden. Dies ist der schnellste Weg von „Was schneidet am besten ab?“ zu „Ich verwende es in der Produktion.“

fonts​

Lädt PUA-Webfonts für Skript-Konverter konstruierter Sprachen herunter und verwaltet sie. Sprachen, die Private-Use-Area-Zeichen verwenden (Klingonisch, Sindarin, Kryptonisch), benötigen benutzerdefinierte Webfonts, um ihre Skripte darzustellen. Dieser Befehl lädt sie aus verifizierten Open-Source-Repositorys herunter.

champollion fonts list                           # show needed fonts
champollion fonts install                        # download all needed fonts
champollion fonts install --css                  # also generate CSS snippet
champollion fonts install --dir ./public/fonts   # custom output directory
UnterbefehlAusgabe
listZeigt an, welche PUA-Fonts benötigt werden und deren Installationsstatus
installLädt Fonts für konfigurierte Sprachen herunter
OptionWirkung
--dir <path>Font-Ausgabeverzeichnis überschreiben (automatisch aus dem Projekttyp erkannt)
--cssEin conlang-fonts.css-Snippet zusammen mit den Fonts generieren
--config <path>Pfad zur Konfigurationsdatei (verwendet, um zu erkennen, welche Sprachen Fonts benötigen)

Automatische Erkennung: Das Ausgabeverzeichnis wird aus Ihrer Projektstruktur abgeleitet:

  • Docusaurus → static/fonts/ oder website/static/fonts/
  • Hugo → static/fonts/
  • Standard → public/fonts/

Native Unicode-Konverter (crk → Cree-Silbenschrift, sr → serbisches Kyrillisch) erfordern KEINE Font-Installation.

Siehe Conlangs, Scripts & Orthography für vollständige PUA-Font-Details.

Dreischichtige Pipeline​

Verwenden Sie lint, sync und audit gemeinsam für eine kugelsichere i18n:

package.json
{
  "scripts": {
    "i18n:lint": "champollion lint",
    "i18n:sync": "champollion sync",
    "i18n:audit": "champollion audit"
  }
}
SchichtBefehlWannZweck
LintlintPre-CommitCommits mit hartkodierten Zeichenketten blockieren
SyncsyncPost-Commit / CIFehlende und geänderte Schlüssel übersetzen
VerifyverifyPost-Sync / CIBestätigen, dass Übersetzungen vorhanden und korrekt sind
AuditauditBuild-SchrittBereitstellung scheitern lassen, falls eine Locale [EN]-Markierungen aufweist

Siehe auch​