Mehrsprachige Doku (DE / EN)

Was: Die Dokumentation auf docs.cockpit-os.de kann neben Deutsch auch Englisch anbieten — Sprachumschalter oben rechts in der Navbar.

Warum: Internationale Center-Betreiber, Partner und Entwickler:innen profitieren von EN; der Hauptinhalt bleibt auf Deutsch gepflegt.

Wer: Team (Doku-Pflege), nicht Redaktion im Dashboard.

---

Technik

Baustein	Rolle
Docusaurus i18n (eingebaut)	Locales de (Standard) + en, Ausgabe unter /en/…
docusaurus-i18n	CLI: übersetzt Markdown aus docs/ nach i18n/en/… per OpenAI
OpenAI	Gleicher Schlüssel wie im Cockpit (OPENAI_API_KEY) — Modell standardmäßig gpt-4o-mini

Hinweis: Ohne EN-Dateien in i18n/en/ zeigt die englische Locale oft noch deutschen Fallback-Text — das ist verwirrend für Leser:innen. Nach größeren DE-Änderungen EN nachziehen oder gezielt priorisieren (siehe unten).

---

Erstes Setup (einmalig)

cd cockpit-docs
npm run write-translations -- --locale en

Legt UI-Strings (code.json, Navbar-Labels) unter i18n/en/ an.

---

Übersetzung ausführen

Lokal (API-Key aus Umgebung, nicht committen):

cd cockpit-docs
export OPENAI_API_KEY="sk-…"   # oder aus .env des Projekts
npm run docs:translate

Entspricht:

npx docusaurus-i18n --project . --model gpt-4o-mini

Optional andere Base-URL (z. B. Azure/OpenRouter):

npx docusaurus-i18n --baseUrl https://… --model gpt-4o-mini

Kosten & Dauer (realistisch):

Modus	Umfang	Dauer (grobe Schätzung)
Priorität	13 Kernseiten	~3–8 Minuten
Voll-Lauf	~128 .md, eine API-Anfrage pro Datei, sequentiell	oft 45–90+ Minuten

Langsam wird es vor allem bei riesigen Referenzseiten (z. B. mec-shared-bausteine.md >1.000 Zeilen) — pro Datei ein kompletter LLM-Durchlauf.

Schnell (empfohlen für den Alltag):

cd cockpit-docs
export OPENAI_API_KEY="sk-…"
npm run docs:translate:priority

Voll-Lauf nur gelegentlich (z. B. über Nacht) oder abbrechen (Ctrl+C) — bereits übersetzte Dateien bleiben gespeichert; beim nächsten docs:translate werden unveränderte DE-Quellen per _i18n_hash übersprungen.

---

Empfohlener Workflow im Team

1. DE-Inhalt in docs/ schreiben oder ändern (wie bisher).
2. Bei sichtbarer Lieferung: pnpm docs:check (Alter Code vs. Doku).
3. Wenn EN mitziehen soll: npm run docs:translate (oder nur geänderte Dateien manuell in i18n/en/ pflegen).
4. Lokal prüfen: npm run start -- --locale en
5. Build: npm run build (baut DE + EN).
6. Deploy wie gewohnt (Render).

Qualität: KI-Übersetzung für Handbücher reviewen (Fachbegriffe: Center, Shop, Freigabe, v0). DeepL im Dashboard betrifft Center-Website-Inhalte, nicht diese Doku — siehe DeepL im Dashboard.

---

Priorität EN (Pilot)

Priorität	Seiten
Hoch	intro, content-creator-handbuch/start-hier, plattform/investoren-und-partner, developer-guide/start-hier-entwicklung
Mittel	Navbar-Bereiche Dashboard, Center-Website (Intro + Feature-Katalog)
Niedrig	Legacy-Checklisten, sehr lange Referenzseiten

Vollautomatischer Lauf übersetzt alles; für Pilot kann das Team zuerst nur die genannten DE-Dateien anlegen und docusaurus-i18n laufen lassen (überschreibt/ergänzt passende Pfade unter i18n/en/).

---

So testen

1. cd cockpit-docs && npm run start
2. Navbar → English
3. /en/content-creator-handbuch/start-hier — Text sollte Englisch sein, nicht Deutsch-Fallback
4. npm run build ohne Fehler

---

Betrieb

• Env: OPENAI_API_KEY nur lokal/CI für Translate-Job, nicht im statischen Doku-Build auf Render nötig (übersetzte Dateien liegen im Git).
• Suche: Lokale Suche ist für de und en konfiguriert (docusaurus.config.ts).

---

← Dokumentation im Team-Prozess · Doku-Zielgruppen