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
│   └── pt-BR/         # Brazilian Portuguese
├── 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
└── .intlayer/         # Intlayer generated UI translation files (auto-generated)

Internationalisierung (i18n)​

Die Dokumentation verwendet das integrierte i18n-System von Docusaurus mit Englisch als Standardsprache. Übersetzte Inhalte befinden sich in i18n/{locale}/docusaurus-plugin-content-docs/current/ und spiegeln die Struktur des docs/-Ordners 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-Zeichenfolgen (aus Docusaurus-Theme und benutzerdefinierten Komponenten) in JSON-Übersetzungsdateien. Das Skript pnpm translate verwendet KI, um sowohl die Markdown-Dokumentation als auch die UI-JSON-Dateien zu übersetzen.

important

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

Unterstützte Gebietsschemas​

LocaleSpracheVerzeichnis
enEnglisch (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/
pt-BRBrasilianisches Portugiesischi18n/pt-BR/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 befindet sich in Englisch (docs/), und Übersetzungen werden für Deutsch, Französisch, Spanisch und Brasilianisches Portugiesisch generiert.

Funktionsweise der Übersetzung​

  1. UI-Zeichenfolgen-Extraktion: pnpm write-translations extrahiert übersetzbare Zeichenfolgen aus Docusaurus-UI und benutzerdefinierten Komponenten in JSON-Dateien in i18n/en/

  2. Inhaltsübersetzung: pnpm translate verwendet OpenRouter KI zum Übersetzen:

    • Markdown-Dateien von docs/ → i18n/{locale}/docusaurus-plugin-content-docs/current/
    • JSON-UI-Zeichenfolgen von i18n/en/ → i18n/{locale}/
    • SVG-Dateien von static/img/duplistatus*.svg (übersetzt Text in SVGs und exportiert als PNG über Inkscape)

  3. Build: pnpm build generiert statische HTML-Dateien für alle Locales in build/ (ein Unterverzeichnis pro Locale)

Übersetzung ausführen​

cd documentation
pnpm translate                       # Translate everything to all locales
pnpm translate --force               # force the translation of all files
pnpm translate --locale fr           # Translate only to French
pnpm translate --no-svg              # Skip SVG translation
pnpm translate --path docs/intro.md  # Translate specific file
pnpm translate:status                # Show the status of translation of all files

Für detaillierte Optionen, Caching-Verwaltung, Fehlerbehebung und das Glossarsystem siehe Übersetzungs-Workflow.

Manuelle Übersetzungsüberschreibungen​

Wenn Sie eine Übersetzung manuell anpassen müssen:

  1. Fügen Sie die Begriffe zu glossary-user.csv hinzu
  2. Löschen Sie die Cache-Einträge für diese Begriffe mithilfe des webbasierten Cache-Bearbeitungstools
  3. Führen Sie die Übersetzung erneut mit pnpm translate --force aus

Häufige Befehle​

Alle Befehle sollten aus dem Verzeichnis documentation 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 unter http://localhost:3000 (oder dem nächsten verfügbaren Port) erreichbar.

Erstellen​

Erstellen Sie die Dokumentationswebsite für die Produktion:

cd documentation
pnpm build

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

Produktions-Build bereitstellen​

Zeigen Sie den Production-Build lokal in der Vorschau 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 durchführen
  • pnpm write-heading-ids - Überschrift-IDs im internen Docusaurus-Format generieren (ändert Markdown-Dateien nicht)
  • pnpm heading-ids - Explizite Anker-IDs {#id} zu allen Markdown-Überschriften hinzufügen (ändert Dateien; stellt konsistente IDs über Übersetzungen hinweg sicher)

README.md generieren​

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

Um die README.md-Datei zu generieren oder zu aktualisieren:

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

Dieses Skript:

  • Extrahiert die aktuelle Version aus package.json und fügt ein Versions-Badge hinzu
  • Kopiert Inhalte aus documentation/docs/intro.md
  • Konvertiert Docusaurus-Admonitions (note, tip, warning, etc.) in GitHub-style Warnungen
  • Konvertiert alle relativen Docusaurus-Links in absolute GitHub-Dokumentations-URLs (https://wsj-br.github.io/duplistatus/...)
  • Konvertiert Bildpfade von /img/ zu documentation/static/img/ für GitHub-Kompatibilität
  • Entfernt den Migration IMPORTANT-Block und fügt einen Abschnitt „Migration Information" mit einem Link zur Docusaurus-Dokumentation hinzu
  • Generiert ein Inhaltsverzeichnis mit doctoc
  • Generiert README_dockerhub.md mit Docker-Hub-kompatibler Formatierung (konvertiert Bilder und Links in absolute URLs, konvertiert GitHub-Warnungen in Emoji-basiertes Format)
  • Generiert GitHub-Versionshinweise (RELEASE_NOTES_github_VERSION.md) aus documentation/docs/release-notes/VERSION.md (konvertiert Links und Bilder in absolute URLs)

README für Docker Hub aktualisieren​

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

  • Kopiert README.md zu README_dockerhub.md
  • Konvertiert relative Bildpfade zu absoluten GitHub-Raw-URLs
  • Konvertiert relative Dokumentlinks zu absoluten GitHub-Blob-URLs
  • Konvertiert GitHub-Style-Warnungen ([!NOTE], [!WARNING] usw.) 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 Skript generate-readme-from-intro.sh generiert automatisch GitHub-Versionshinweise bei der Ausführung. Es:

  • Liest die Versionshinweise 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 zu absoluten GitHub-Dokumentations-URLs (https://wsj-br.github.io/duplistatus/...)
  • Konvertiert Bildpfade zu GitHub-Raw-URLs (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) für die ordnungsgemäße Anzeige in Versionsbeschreibungen
  • 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 Release-Notes-Datei kann direkt in die GitHub-Release-Beschreibung kopiert und eingefügt werden. Alle Links und Bilder funktionieren korrekt im GitHub-Release-Kontext.

Screenshots für die Dokumentation aufnehmen​

pnpm take-screenshots

Oder direkt ausführen: pnpm take-screenshots (verwenden Sie --env-file=.env, wenn Umgebungsvariablen benötigt werden).

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

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

Anforderungen:

  • Der Entwicklungsserver muss auf http://localhost:8666 laufen
  • Umgebungsvariablen müssen gesetzt sein, fügen Sie diese zu Ihrer .env-Datei hinzu oder exportieren Sie sie:
    • ADMIN_PASSWORD: Passwort für Admin-Konto
    • USER_PASSWORD: Passwort für reguläres Benutzerkonto

Optionen: --locale beschränkt Screenshots auf eine oder mehrere Sprachen (kommagetrennt). Wenn weggelassen, werden alle Sprachen erfasst. Gültige Sprachen: en, de, fr, es, pt-BR. 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
# Multiple locales:
pnpm take-screenshots --locale en,de,pt-BR

Bereitstellung der Dokumentation​

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

Wenn Sie das Token haben, speichern Sie es im Git-Anmeldeinformationsspeicher (z.B. mit git config credential.helper store oder dem Anmeldeinformationsmanager Ihres Systems).

Um die Dokumentation dann auf GitHub Pages zu veröffentlichen, führen Sie den folgenden Befehl aus dem Verzeichnis documentation aus:

pnpm run deploy

Dies erstellt die Dokumentation und pusht sie in den gh-pages-Branch des Repositorys. Die Dokumentation ist dann unter https://wsj-br.github.io/duplistatus/ verfügbar.

Arbeiten mit Dokumentation​

Für den vollständigen Übersetzungs-Workflow (Glossar-Verwaltung, KI-Übersetzung, Caching-Verwaltung), siehe Übersetzungs-Workflow.

Quelldateien​

  • Dokumentationsinhalt: Englische Markdown-Dateien in documentation/docs/
  • UI-Übersetzungen: Englische JSON-Dateien in documentation/i18n/en/ (automatisch generiert durch pnpm write-translations)
  • Seitennavigation: documentation/sidebars.ts
  • Docusaurus-Konfiguration: documentation/docusaurus.config.ts
  • Benutzerdefinierte React-Komponenten: documentation/src/components/
  • Statische Assets: documentation/static/
  • Haupthomepage: 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-Zeichenfolgen enthält, führen Sie pnpm write-translations aus, um sie zu extrahieren
  4. Führen Sie pnpm translate aus, um die neuen Zeichenfolgen in alle Gebietsschemas zu übersetzen

Neue Dokumentationsseiten hinzufügen​

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

Statische Assets​

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

Erstellen & 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-Gebietsschema und einem anderen Gebietsschema, um sicherzustellen, dass Übersetzungen korrekt erscheinen.