Zum Hauptinhalt springen

Dokumentationswerkzeuge

Die Dokumentation wird mit Docusaurus erstellt und befindet sich im Ordner documentation. Die Dokumentation wird auf GitHub Pages gehostet und ist nicht mehr im Docker-Container-Image enthalten.

Ordnerstruktur​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   ├── hi-Latn/       # Hindi (Roman)
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   └── pages/         # Additional pages (e.g., 404)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

Internationalisierung (i18n)​

Die Dokumentation nutzt das integrierte i18n-System von Docusaurus mit Englisch als Standard-Locale. Übersetzte Inhalte befinden sich in i18n/{locale}/docusaurus-plugin-content-docs/current/ und spiegeln die Struktur des Ordners docs/ wider.

  • Quelldateien: docs/**/*.md (Englisch)
  • Übersetzte Dateien: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • UI-Übersetzungen: i18n/{locale}/docusaurus-theme-classic/*.json und andere JSON-Dateien
  • Lokalisierte Screenshots: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, generiert durch pnpm take-screenhots im Basisverzeichnis.

Der Befehl pnpm write-translations extrahiert UI-Texte (aus Docusaurus-Theme und benutzerdefinierten Komponenten) in JSON-Übersetzungsdateien. Das Skript pnpm translate (aus documentation/, delegiert zum Repository-Stamm) führt ai-i18n-tools aus, um Markdown-, JSON- und SVG-Dateien gemäß ai-i18n-tools.config.json zu übersetzen.

important

Bearbeiten Sie nur Dateien in docs/ und die Quell-JSON-Dateien in i18n/en/. Die übersetzten Markdown-Dateien in i18n/{other-locales}/ werden automatisch generiert und sollten nicht manuell bearbeitet werden.

Unterstützte Gebietsschemas​

LocaleSpracheVerzeichnis
en-GBEnglisch (Standard)docs/ (Quelle)
deDeutschi18n/de/docusaurus-plugin-content-docs/current/
esSpanischi18n/es/docusaurus-plugin-content-docs/current/
frFranzösischi18n/fr/docusaurus-plugin-content-docs/current/
hi-LatnHindi (Lateinisch)i18n/hi-Latn/docusaurus-plugin-content-docs/current/
pt-BRBrasilianisches Portugiesischi18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansVereinfachtes Chinesischi18n/zh-Hans/docusaurus-plugin-content-docs/current/

Dokumentation übersetzen​

Die Dokumentation verwendet ein KI-gestütztes Übersetzungssystem, um sowohl Inhalte (Markdown-Dateien) als auch UI-Zeichenfolgen (aus Docusaurus und benutzerdefinierten Komponenten) zu übersetzen. Der Quellinhalt ist auf Englisch (docs/), und es werden Übersetzungen für Deutsch, Französisch, Spanisch, Brasilianisches Portugiesisch, Hindi (Lateinisch) und Vereinfachtes Chinesisch generiert.

Funktionsweise der Übersetzung​

  1. Docusaurus UI-Texte: pnpm write-translations extrahiert Theme- und benutzerdefinierte Texte in i18n/en/*.json.
  2. KI-Übersetzung (OpenRouter; Konfiguration in ai-i18n-tools.config.json im Repository-Stamm): ausgehend von documentation/ führt pnpm translate das Skript i18n:translate im Stammverzeichnis aus (Übersetzung von UI-Texten, SVGs sowie Docusaurus-Markdown/JSON) in documentation/i18n/ und src/locales/ gemäß Konfiguration.
  3. Erstellung: pnpm build generiert statische HTML-Dateien für alle Sprachen unter documentation/build/.

Übersetzung ausführen​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs)
pnpm translate:docs
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

CLI-Flags werden von ai-i18n-tools definiert; führen Sie pnpm exec ai-i18n-tools --help im Repository-Stamm aus oder sehen Sie sich den Übersetzungsworkflow an.

Manuelle Übersetzungsüberschreibungen​

Bearbeiten Sie documentation/glossary-user.csv (und löschen Sie optional veraltete Einträge unter .translation-cache/ im Repository-Stamm), und führen Sie dann den entsprechenden pnpm translate:*-Befehl erneut aus.

Häufige Befehle​

Alle Befehle sollten aus dem Verzeichnis documentation heraus ausgeführt werden:

Entwicklung​

Starten Sie den Entwicklungsserver mit Hot-Reload für ein bestimmtes Gebietsschema:

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

Die Website ist verfügbar unter http://localhost:3000 (oder dem nächsten verfügbaren Port).

Erstellen​

Erstellen Sie die Dokumentationswebsite für die Produktion:

cd documentation
pnpm build

Dies erzeugt statische HTML-Dateien im Verzeichnis documentation/build.

Produktions-Build bereitstellen​

Zeigen Sie den Produktionsbuild lokal an:

cd documentation
pnpm serve

Dies stellt die erstellte Website aus dem Verzeichnis documentation/build bereit.

Weitere nützliche Befehle​

  • pnpm clear – Docusaurus-Cache löschen
  • pnpm typecheck – TypeScript-Typüberprüfung ausführen
  • pnpm write-heading-ids – Explizite {#id}-Überschriftanker gemäß Docusaurus-Regeln in Markdown schreiben (aus documentation/ ausführen, um stabile Links über Übersetzungen hinweg zu gewährleisten)

README.md generieren​

Die Datei README.md des Projekts wird automatisch aus documentation/docs/intro.md generiert, um die README des GitHub-Repositorys mit der Docusaurus-Dokumentation synchron zu halten.

So generieren oder aktualisieren Sie die Datei README.md:

./scripts/generate-readme-from-intro.sh

Dieses Skript:

  • Extrahiert die aktuelle Version aus package.json und fügt ein Versionsbadge hinzu
  • Kopiert Inhalte aus documentation/docs/intro.md
  • Konvertiert Docusaurus-Hinweise (Hinweis, Tipp, Warnung usw.) in GitHub-ähnliche Warnungen
  • Konvertiert alle relativen Docusaurus-Links in absolute GitHub-Docs-URLs (https://wsj-br.github.io/duplistatus/...)
  • Konvertiert Bildpfade von /img/ nach documentation/static/img/ zur Kompatibilität mit GitHub
  • Entfernt den Migrations-IMPORTANT-Block und fügt einen Abschnitt „Migrationsinformationen“ mit einem Link zu den Docusaurus-Dokumenten hinzu
  • Erstellt ein Inhaltsverzeichnis mithilfe von doctoc
  • Generiert README_dockerhub.md mit Docker-Hub-kompatibler Formatierung (wandelt Bilder und Links in absolute URLs um, konvertiert GitHub-Hinweise in Emoji-basiertes Format)
  • Generiert GitHub-Releasehinweise (RELEASE_NOTES_github_VERSION.md) aus documentation/docs/release-notes/VERSION.md (wandelt Links und Bilder in absolute URLs um)

README für Docker Hub aktualisieren​

Das generate-readme-from-intro.sh-Skript generiert automatisch README_dockerhub.md mit Docker-Hub-kompatibler Formatierung. Es:

  • Kopiert README.md nach README_dockerhub.md
  • Konvertiert relative Bildpfade in absolute GitHub-Roh-URLs
  • Konvertiert relative Dokumentlinks in absolute GitHub-Blob-URLs
  • Konvertiert GitHub-Style-Hinweise ([!NOTE], [!WARNING], etc.) in Emoji-basiertes Format für bessere Docker-Hub-Kompatibilität
  • Stellt sicher, dass alle Bilder und Links auf Docker Hub korrekt funktionieren

GitHub-Versionshinweise generieren​

Das generate-readme-from-intro.sh-Skript generiert automatisch GitHub-Releasehinweise beim Ausführen. Es:

  • Liest die Releasehinweise aus documentation/docs/release-notes/VERSION.md (wobei VERSION aus package.json extrahiert wird)
  • Ändert den Titel von "# Version xxxx" zu "# Release Notes - Version xxxxx"
  • Konvertiert relative Markdown-Links in absolute GitHub-Dokumentations-URLs (https://wsj-br.github.io/duplistatus/...)
  • Konvertiert Bildpfade in GitHub-Roh-URLs (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...), damit sie in Release-Beschreibungen korrekt angezeigt werden
  • Verarbeitet relative Pfade mit ../-Präfix
  • Behält absolute URLs (http:// und https://) unverändert
  • Erstellt RELEASE_NOTES_github_VERSION.md im Projektstammverzeichnis

Beispiel:

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

Die generierte Releasehinweis-Datei kann direkt in die GitHub-Release-Beschreibung kopiert werden. Alle Links und Bilder funktionieren im Kontext des GitHub-Releases korrekt.

Screenshots für die Dokumentation aufnehmen​

pnpm take-screenshots

Oder direkt ausführen: pnpm take-screenshots (bei Bedarf mit --env-file=.env für Umgebungsvariablen).

Dieses Skript nimmt automatisch Screenshots der Anwendung für Dokumentationszwecke auf. Es:

  • Startet einen Headless-Browser (Playwright Chromium)
  • Meldet sich als Admin und als regulärer Benutzer an
  • Navigiert durch verschiedene Seiten (Dashboard, Serverdetails, Einstellungen usw.)
  • Erstellt Screenshots mit verschiedenen Ansichtsfenstergrößen
  • Speichert Screenshots in documentation/static/assets/ (Englisch) oder documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (andere Sprachvarianten)

Voraussetzungen:

  • Der Entwicklungsserver muss auf http://localhost:8666 laufen
  • Der Playwright Chromium-Browser muss installiert sein (führen Sie pnpm take-screenshots:install einmal aus, was playwright install chromium ausführt)
  • Umgebungsvariablen müssen gesetzt sein, fügen Sie diese zu Ihrer .env-Datei hinzu oder exportieren Sie sie:
    • ADMIN_PASSWORD: Passwort für das Admin-Konto
    • USER_PASSWORD: Passwort für das reguläre Benutzerkonto

Optionen: --locale beschränkt Screenshots auf eine oder mehrere Sprachen (durch Kommas getrennt). Wenn es weggelassen wird, werden alle Sprachen erfasst. Gültige Sprachen: en-GB, de, fr, es, pt-BR, hi-Latn, zh-Hans. Verwenden Sie -h oder --help, um die Verwendung anzuzeigen.

Beispiel:

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,de,pt-BR

Bereitstellung der Dokumentation​

Um die Dokumentation auf GitHub Pages bereitzustellen, müssen Sie ein persönliches GitHub-Zugriffstoken generieren. Gehen Sie zu GitHub Personal Access Tokens und erstellen Sie ein neues Token mit dem repo-Bereich.

Sobald Sie über das Token verfügen, speichern Sie es im Git-Anmeldeinformations-Store (z. B. mithilfe von git config credential.helper store oder dem Anmeldeinformations-Manager Ihres Systems).

Führen Sie dann den folgenden Befehl aus dem Verzeichnis documentation aus, um die Dokumentation auf GitHub Pages bereitzustellen:

pnpm run deploy

Dadurch wird die Dokumentation erstellt und in den Branch gh-pages des Repositorys gepusht, und die Dokumentation ist unter https://wsj-br.github.io/duplistatus/ verfügbar.

Arbeiten mit Dokumentation​

Informationen zum vollständigen Übersetzungsworkflow (Glossarverwaltung, KI-Übersetzung, Cache-Verwaltung) finden Sie unter Übersetzungsworkflow.

Quelldateien​

  • Dokumentationsinhalt: Englische Markdown-Dateien in documentation/docs/
  • UI-Übersetzungen: Englische JSON-Dateien in documentation/i18n/en/ (automatisch generiert von pnpm write-translations)
  • Seitenleisten-Navigation: documentation/sidebars.ts
  • Docusaurus-Konfiguration: documentation/docusaurus.config.ts
  • Benutzerdefinierte React-Komponenten: documentation/src/components/
  • Statische Assets: documentation/static/
  • Hauptstartseite: documentation/docs/intro.md (Quelle zur Generierung von README.md)

Neue Komponenten hinzufügen​

  1. Erstellen Sie Ihre React-Komponente in documentation/src/components/
  2. Exportieren Sie sie aus documentation/src/theme/MDXComponents.js, um sie in MDX verfügbar zu machen
  3. Wenn die Komponente übersetzbare UI-Texte enthält, führen Sie pnpm write-translations aus, um diese zu extrahieren
  4. Führen Sie pnpm translate aus, um die neuen Texte in alle Sprachen zu übersetzen

Neue Dokumentationsseiten hinzufügen​

  1. Erstellen Sie eine neue .md-Datei in documentation/docs/ (oder einem Unterverzeichnis)
  2. Fügen Sie sie der Seitenleiste in documentation/sidebars.ts hinzu
  3. Führen Sie pnpm write-translations aus, um die Struktur der Übersetzungsdateien zu aktualisieren
  4. Führen Sie pnpm write-heading-ids aus, um Überschriften-IDs (Anker) zu generieren
  5. Führen Sie pnpm translate aus, um die neue Seite in alle Sprachen zu übersetzen
  6. Erstellen und testen: pnpm build

Statische Assets​

  • Bilder: Platzieren Sie sie in documentation/static/img/ und verweisen Sie darauf mit /img/filename.png in Markdown
  • Downloads/PDFs: Platzieren Sie sie in documentation/static/ und verweisen Sie darauf mit /filename.pdf
  • Sprachspezifische Assets: Wenn ein Asset sprachspezifisch sein muss (z. B. Screenshots), platzieren Sie es in documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/

Erstellen und Testen​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

Testen Sie Ihre Änderungen immer mindestens im Standard-Englisch und einer weiteren Sprache, um sicherzustellen, dass die Übersetzungen korrekt angezeigt werden.