Internationalisierung¶

CodexSpec unterstützt mehrere Sprachen durch dynamische LLM-Übersetzung und bietet mehrsprachige Dokumentation für GitHub Pages.

Befehlsvorlagen-Übersetzung¶

Funktionsweise¶

Einzelne englische Vorlagen: Alle Befehlsvorlagen bleiben auf Englisch
Sprachkonfiguration: Das Projekt gibt die bevorzugte Ausgabesprache an
Dynamische Übersetzung: Claude übersetzt Inhalte zur Laufzeit

Sprach-Dimensionen¶

CodexSpec unterteilt die Sprache in vier unabhängig konfigurierbare Dimensionen. output ist die Basis; die anderen überschreiben sie und fallen darauf (und dann auf en) zurück, wenn sie nicht gesetzt sind.

Dimension	`config.yml`-Schlüssel	Bei init setzen	Später setzen	Steuert	Fällt zurück auf
Output (Basis)	`output`	`--lang`	`config --set-lang`	Basis für die anderen drei	`en`
Interaction	`interaction`	`--interaction-lang`	`config --set-interaction-lang`	LLM-Dialog + CLI-Ausgabe	output → `en`
Document	`document`	`--document-lang`	`config --set-document-lang`	generierte Spec/Plan/Tasks	output → `en`
Commit	`commit`	`--commit-lang`	`config --set-commit-lang`	Git-Commit-Nachrichten	output → `en`
Templates	`templates`	—	—	Quelle der Befehlsvorlagen (immer `en`)	—

Sprache einstellen¶

Während der Initialisierung¶

# Chinesische Ausgabe (setzt die Basis output)
codexspec init my-project --lang zh-CN

# Vollständig nicht-interaktiv: zh-CN-Basis, englische Commit-Nachrichten
codexspec init my-project --lang zh-CN --commit-lang en

# Jede Dimension explizit festlegen (skriptbar, keine Prompts)
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

Die erstmalige Initialisierung in einem TTY ohne --lang (und ohne alle drei Dimensions-Flags) fragt nach einer Basissprache; in einem Nicht-TTY (CI/Skripte) wird standardmäßig en verwendet. Ein erneuter init-Aufruf behält jeden Sprach-Schlüssel bei, den Sie nicht angegeben haben.

Nach der Initialisierung¶

# Aktuelle Konfiguration anzeigen
codexspec config

# Eine einzelne Dimension ändern
codexspec config --set-lang zh-CN
codexspec config --set-interaction-lang zh-CN
codexspec config --set-document-lang en
codexspec config --set-commit-lang en

# workflow.auto_next umschalten (bare Flag schaltet um; oder on/off explizit übergeben)
codexspec config --auto-next

# Unterstützte Sprachen auflisten
codexspec config --list-langs

Konfigurationsdatei¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"        # Basissprache; die drei unten fallen darauf zurück, dann "en"
  interaction: "zh-CN"   # LLM-Dialog + codexspec CLI-Ausgabe (optional → Standardwert ist output)
  document: "en"         # Generierte Anforderungen/Spec/Plan/Tasks (optional → Standardwert ist output)
  commit: "en"           # Git-Commit-Nachrichten (optional → Standardwert ist output)
  templates: "en"        # Als "en" belassen

project:
  ai: "claude"          # claude | codex | both — welcher AI-Assistent für dieses Projekt vorgesehen ist
  created: "2025-02-15"

GitHub-Pages-Dokumentation i18n¶

Docs-Site-Sprachen vs. CLI-/Laufzeit-Sprachen – nicht vermischen.

Dokumentations-Site (dieser Abschnitt): 8 Sprachen. Die von MkDocs gebaute GitHub-Pages-Site liefert genau die acht unten aufgeführten Locales (en, zh, ja, ko, es, fr, de, pt-BR). Das ist eine feste Menge, gesteuert durch das docs/{lang}/-Verzeichnislayout und das mkdocs-i18n-Plugin.

CLI / Laufzeit (Abschnitt oben): 13 Sprachen. Die language.*-Dimensionen, die Sie in .codexspec/config.yml konfigurieren, akzeptieren 13 unterstützte Codes (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi), die das LLM im Flug übersetzt. Die kanonische Liste steht in der Tabelle „Supported Languages" in der Projekt-README.

Die beiden Mengen überschneiden sich, sind aber nicht identisch: Die Docs-Site hat keine zh-TW/ru/it/ar/hi-Locales, und das CLI verwendet nicht die bloßen zh/de/...-Codes, die MkDocs als Ordnernamen nutzt.

CodexSpecs Dokumentations-Site unterstützt 8 Sprachen mit MkDocs und dem mkdocs-i18n-Plugin.

Unterstützte Sprachen¶

Code	Sprache
`en`	Englisch (Standard)
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português (Brasil)

Verzeichnisstruktur¶

docs/
├── en/                 # Englisch (Quelle)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # Chinesische Übersetzung
├── ja/                 # Japanische Übersetzung
├── ko/                 # Koreanische Übersetzung
├── es/                 # Spanische Übersetzung
├── fr/                 # Französische Übersetzung
├── de/                 # Deutsche Übersetzung
└── pt-BR/              # Portugiesische (Brasilien) Übersetzung

Dokumentation übersetzen (nur für Maintainer)¶

Hinweis: Die Befehle /codexspec:translate-docs und /codexspec:check-i18n-semantics sind Werkzeuge ausschließlich für CodexSpec-Maintainer. Sie sind eng an das MkDocs-i18n-Layout dieses Repositorys (docs/{lang}/) und an das nur im Repo vorhandene Glossar docs/i18n/glossary.yml gekoppelt. Sie werden nicht über codexspec init an Benutzerprojekte verteilt und stehen Endbenutzern nicht als Slash-Befehle zur Verfügung.

Wenn Sie an CodexSpec selbst arbeiten, liegen diese Befehle unter .claude/commands/codexspec/ und werden wie jeder andere Slash-Befehl aufgerufen. Endbenutzer, die die Dokumentation ihres eigenen Projekts übersetzen möchten, sollten Claude direkt in ihrem bevorzugten Workflow verwenden.

CodexSpec-Maintainer können den Befehl /codexspec:translate-docs zum Übersetzen der Dokumentation verwenden:

# Nach Chinesisch übersetzen
/codexspec:translate-docs --lang zh

# Spezifische Datei nach Japanisch übersetzen
/codexspec:translate-docs user-guide/installation.md --lang ja

# Inkrementelle Übersetzung (nur geänderte Dateien)
/codexspec:translate-docs --lang ko --incremental

# Vorschaumodus (keine Dateiänderungen)
/codexspec:translate-docs --lang es --dry-run

Übersetzungs-Glossar¶

Das Glossar unter docs/i18n/glossary.yml (nur im Repo) stellt konsistente Terminologie beim Übersetzen von CodexSpecs eigener Dokumentation sicher:

version: "1.0"

# Begriffe, die auf Englisch bleiben
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# Übersetzungen für häufige Begriffe
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# Intelligente Regeln für Sonderfälle
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

Übersetzungsmethodik¶

Übersetzungen sollen in Ihrer Sprache natürlich lesbar sein und nicht als wortwörtliche Abbilder des Englischen:

Sinn vor Wörtern. Jeder Abschnitt wird nach dem übersetzt, was er vermittelt, und dann mit der Ausdrucksweise und Satzstruktur der Zielsprache neu formuliert.
Englische Begriffe bleiben, wenn sie klarer sind. Fachbegriffe ohne passendes Äquivalent – oder die auf Englisch geläufiger sind – werden im Englischen belassen, statt sie holprig zu übersetzen. Beispielsweise wird „AI coding agent" zu einem natürlichen Ausdruck wie „AI-Programmierassistent" und nicht zu einer starren wortwörtlichen Übersetzung.
Muttersprachliche Flüssigkeit. Ziel ist ein Text, der sich liest, als wäre er ursprünglich in Ihrer Sprache verfasst worden.

Qualitätsprüfungen¶

Strukturprüfung¶

Verifiziert, dass alle Sprachverzeichnisse dieselbe Dateistruktur haben:

./scripts/bash/check-i18n-structure.sh

Vollständigkeitsprüfung¶

Erkennt unübersetzten englischen Inhalt in Übersetzungen:

./scripts/bash/check-i18n-completeness.sh

Semantische Prüfung (nur für Maintainer)¶

Die KI-gestützte semantische Konsistenzanalyse ist ausschließlich für CodexSpec-Maintainer über den internen Befehl verfügbar (siehe den Hinweis „nur für Maintainer" oben):

/codexspec:check-i18n-semantics --lang de

CI/CD-Integration¶

Der Workflow .github/workflows/docs-i18n.yml ist ausschließlich ein Build-Gate: Bei jeder Änderung an docs/** / mkdocs.yml (Push auf main und Pull Requests) führt er mkdocs build --strict über alle Sprachversionen aus, um Build-Fehler, defekte Links und fehlerhafte Inhalte zu erkennen. Er übersetzt nichts.

Übersetzungen werden manuell über /codexspec:translate-docs erzeugt und committet (siehe oben), mit der englischen Quelle und allen Übersetzungen in einem geprüften, atomaren Commit. Automatische Übersetzung in CI wurde bewusst entfernt – der frühere Job lief nie tatsächlich (ein fehlerhaftes if übersprang ihn), benötigte einen stehenden API-Schlüssel und hätte ungeprüfte Übersetzungen direkt auf main committet.

Vorteile¶

Kein Übersetzungs-Wartungsaufwand: Keine Notwendigkeit, mehrere Vorlagenversionen zu pflegen
Immer aktuell: Vorlagen-Updates kommen allen Sprachen zugute
Kontextbewusst: Technische Begriffe bleiben bei Bedarf auf Englisch
Automatisierte Qualität: CI stellt Übersetzungskonsistenz sicher
KI-gestützt: Claude bietet kontextbewusste Übersetzungen