Skip to main content

Multilingual Documentation (DE / EN)

What: The documentation at docs.cockpit-os.de can offer English in addition to German — language switcher at the top right of the navbar.

Why: International center operators, partners, and developers benefit from EN; the main content is maintained in German.

Who: Team (documentation maintenance), not editorial team in the dashboard.

Technology​

ComponentRole
Docusaurus i18n (built-in)Locales de (default) + en, output under /en/…
docusaurus-i18nCLI: translates Markdown from docs/ to i18n/en/… via OpenAI
OpenAISame key as in Cockpit (OPENAI_API_KEY) — model default gpt-4o-mini

Note: Without EN files in i18n/en/, the English locale often still shows German fallback text — this can be confusing for readers. After major DE changes, adjust EN or prioritize it (see below).

Initial Setup (one-time)​

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

Creates UI strings (code.json, Navbar labels) in i18n/en/.

Run Translation​

Locally (API key from environment, do not commit):

cd cockpit-docs
export OPENAI_API_KEY="sk-…"   # or from the project's .env
npm run docs:translate

Equivalent to:

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

Optionally specify another base URL (e.g., Azure/OpenRouter):

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

Costs & Duration (realistic):

ModeScopeDuration (rough estimate)
Priority13 core pages~3–8 minutes
Full Run~128 .md, one API request per file, sequentiallyoften 45–90+ minutes

It slows down especially with huge reference pages (e.g., mec-shared-bausteine.md >1,000 lines) — a complete LLM run per file.

Quick (recommended for everyday use):

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

Full Run only occasionally (e.g., overnight) or abort (Ctrl+C) — already translated files remain saved; during the next docs:translate, unchanged DE sources are skipped by _i18n_hash.

  1. DE content in docs/ write or edit (as before).
  2. For visible delivery: pnpm docs:check (old code vs. documentation).
  3. If EN should be updated: npm run docs:translate (or manually maintain only changed files in i18n/en/).
  4. Check locally: npm run start -- --locale en
  5. Build: npm run build (builds DE + EN).
  6. Deploy as usual (Render).

Quality: Review AI translation for manuals (technical terms: Center, Shop, Approval, v0). DeepL in the Dashboard pertains to center website content, not this documentation — see DeepL in Dashboard.

Priority EN (Pilot)​

PriorityPages
Highintro, content-creator-handbuch/start-hier, plattform/investoren-und-partner, developer-guide/start-hier-entwicklung
MediumNavbar areas Dashboard, Center website (Intro + Feature catalog)
LowLegacy checklists, very long reference pages

A fully automated run translates everything; for the pilot, the team can first create the mentioned DE files and run docusaurus-i18n (overwrites/supplements appropriate paths under i18n/en/).

How to Test​

  1. cd cockpit-docs && npm run start
  2. Navbar → English
  3. /en/content-creator-handbuch/start-hier — Text should be in English, not German fallback
  4. npm run build without errors

Operation​

  • Env: OPENAI_API_KEY only locally/CI for translate job, not needed in static documentation build on Render (translated files are in Git).
  • Search: Local search is configured for de and en (docusaurus.config.ts).

← Documentation in Team Process · Documentation Target Groups

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/plattform/doku-i18n