Weiter zum Hauptinhalt

Dokumentationswerkzeuge

Die Dokumentation wird mit Docusaurus erstellt und befindet sich im documentation-Ordner. 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/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

Internationalisierung (i18n)​

Die Dokumentation verwendet 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 docs/-Ordners wider.

  • Quell-Dateien: 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 von pnpm take-screenhots im Basisverzeichnis.

Der Befehl pnpm write-translations extrahiert UI-Zeichenfolgen (aus dem Docusaurus-Design und benutzerdefinierten Komponenten) in JSON-Übersetzungsdateien. Das Skript pnpm translate (aus documentation/, delegiert an das Repository-Root) führt ai-i18n-tools aus, um Markdown, JSON, SVGs und das Landing-HTML gemäß ai-i18n-tools.config.json zu übersetzen.

Die Docs-Startseite ist src/landing/landing.html, umschlossen von src/pages/index.tsx. Bearbeiten Sie die HTML-Datei für Textinhalte; länderspezifische Kopien befinden sich unter src/landing/i18n/ und werden durch pnpm i18n:translate:docs generiert.

important

Bearbeiten Sie nur Dateien in docs/, die Landing-Quelle src/landing/landing.html und die Quell-JSON-Dateien in i18n/en-GB/. Übersetztes Markdown unter i18n/{other-locales}/ und Landing-Kopien unter src/landing/i18n/ werden generiert und sollten nicht manuell bearbeitet werden.

Unterstützte Sprachen​

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/
hiHindii18n/hi/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-Strings (aus Docusaurus und benutzerdefinierten Komponenten) zu übersetzen. Der Quellinhalt ist in Englisch (docs/), und Übersetzungen werden für Deutsch, Französisch, Spanisch, Brasilianisches Portugiesisch, Hindi und Vereinfachtes Chinesisch generiert.

Wie die Übersetzung funktioniert​

  1. Docusaurus UI-Strings: pnpm write-translations extrahiert Design-/Benutzerdefinierte Strings in i18n/en/*.json.
  2. KI-Übersetzung (OpenRouter; Konfiguration in ai-i18n-tools.config.json im Repo-Wurzelverzeichnis): von documentation/, pnpm translate führt das Wurzel-i18n:translate-Skript (UI-Strings, SVGs, Docusaurus Markdown/JSON und Standardbenachrichtigungsvorlagen) in documentation/i18n/, src/locales/ und src/locales/templates/ aus, wie konfiguriert.
  3. Build: pnpm build generiert statisches HTML für alle Sprachen unter documentation/build/.

Ausführen der Übersetzung​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs + json)
pnpm translate:docs
pnpm translate:json
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 aus dem Wurzelverzeichnis des Repos aus oder sehen Sie sich Übersetzungs-Workflow an.

Manuelle Übersetzungsüberschreibungen​

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

Häufige Befehle​

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

Entwicklung​

Starten Sie den Entwicklungsserver mit Hot-Reload für eine bestimmte Sprache:

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 Seite ist unter http://localhost:3000/duplistatus/ (oder dem nächsten verfügbaren Port) verfügbar. Der /duplistatus/ Pfad entspricht den GitHub Pages baseUrl und den Links im Hilfe-Button der App.

Erstellen​

Erstellen Sie die Dokumentationsseite für die Produktion:

cd documentation
pnpm build

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

Bereitstellen des Produktions-Builds​

Vorschau des Produktions-Builds lokal:

cd documentation
pnpm serve

Dies dient die erstellte Seite aus dem documentation/build Verzeichnis.

Weitere nützliche Befehle​

  • pnpm clear - Docusaurus-Cache löschen
  • pnpm typecheck - TypeScript-Typprüfung ausführen
  • pnpm write-heading-ids - Schreiben Sie explizite {/* #id */} Überschriftenanker in Markdown unter Verwendung der Docusaurus MDX-Kommentarsyntax (aus documentation/ ausführen für stabile Links über Übersetzungen hinweg). Die CLI überspringt h1 Titel, die Docusaurus als Seitenleistenbeschriftungen verwendet.

Generierung von README.md​

Die README.md Datei des Projekts wird automatisch aus documentation/docs/intro.md generiert, um das README des GitHub-Repositories 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 von package.json und fügt ein Versionsbadge hinzu
  • Kopiert Inhalte von documentation/docs/intro.md
  • Konvertiert Docusaurus-Warnungen (Notiz, Tipp, Warnung usw.) in GitHub-Stil-Alerts
  • Konvertiert alle relativen Docusaurus-Links in absolute GitHub-Dokumentations-URLs (https://wsj-br.github.io/duplistatus/...)
  • Konvertiert Bildpfade von /img/ nach documentation/static/img/ für die Kompatibilität mit GitHub
  • Entfernt den Migration WICHTIG-Block und fügt einen Abschnitt mit Migrationsinformationen hinzu, der einen Link zu den Docusaurus-Dokumenten enthält
  • Generiert ein Inhaltsverzeichnis mit doctoc
  • Generiert README_dockerhub.md mit Docker Hub-kompatibler Formatierung (konvertiert Bilder und Links in absolute URLs, konvertiert GitHub-Alerts in emoji-basierte Formate)
  • Generiert GitHub-Release-Notizen (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 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 Dokumentenlinks in absolute GitHub-Blob-URLs
  • Konvertiert GitHub-Stil-Alerts ([!NOTE], [!WARNING], usw.) in emoji-basierte Formate für eine bessere Docker Hub-Kompatibilität
  • Stellt sicher, dass alle Bilder und Links auf Docker Hub korrekt funktionieren

GitHub Release-Notizen generieren​

Das generate-readme-from-intro.sh-Skript generiert automatisch GitHub-Release-Notizen, wenn es ausgeführt wird. Es:

  • Liest die Release-Notizen von documentation/docs/release-notes/VERSION.md (wo VERSION von package.json extrahiert wird)
  • Ändert den Titel von "# Version xxxx" zu "# Release-Notizen - 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/...) für die korrekte Anzeige in Release-Beschreibungen
  • Behandelt relative Pfade mit ../-Präfix
  • Bewahrt absolute URLs (http:// und https://) unverändert
  • Erstellt RELEASE_NOTES_github_VERSION.md im Projektstamm

Beispiel:

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

Die generierte Release-Notizdatei kann direkt in die GitHub-Release-Beschreibung kopiert und eingefügt werden. Alle Links und Bilder funktionieren im Kontext der GitHub-Release korrekt.

Screenshots für die Dokumentation erstellen​

pnpm take-screenshots

Oder direkt ausführen: pnpm take-screenshots (verwenden Sie --env-file=.env, falls erforderlich, für Umgebungsvariablen).

Dieses Skript erstellt automatisch Screenshots der Anwendung zu Dokumentationszwecken. Es:

  • Führt nach Umgebungs- und Gesundheitsprüfungen pnpm exec playwright install aus, damit Playwright-Browser vorhanden sind
  • Startet einen headless Browser (Playwright Chromium)
  • Meldet sich als Admin und regulärer Benutzer an
  • Navigiert durch verschiedene Seiten (Dashboard, Serverdetails, Einstellungen usw.)
  • Macht Screenshots in verschiedenen Ansichtsgröß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 werden, fügen Sie diese 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 (kommagetrennt). Wenn weggelassen, werden alle Sprachen erfasst. Gültige Sprachen: en-GB, de, fr, es, pt-BR, hi, 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

Dokumentation bereitstellen​

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.

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

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

pnpm run deploy

Dies wird die Dokumentation erstellen und in den gh-pages-Branch des Repositories pushen, und die Dokumentation wird unter https://wsj-br.github.io/duplistatus/ verfügbar sein.

Arbeiten mit Dokumentation​

Für den vollständigen Übersetzungsworkflow (Glossarverwaltung, KI-Übersetzung, Cache-Verwaltung) siehe Übersetzungsworkflow.

Quelldateien​

  • Dokumentationsinhalt: Englische Markdown-Dateien in documentation/docs/
  • UI-Übersetzungen: Englische JSON-Dateien in documentation/i18n/en/ (automatisch generiert von pnpm write-translations)
  • Sidebar-Navigation: documentation/sidebars.ts
  • Docusaurus-Konfiguration: documentation/docusaurus.config.ts
  • Benutzerdefinierte React-Komponenten: documentation/src/components/
  • Statische Assets: documentation/static/
  • Haupt-Homepage: 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 von documentation/src/theme/MDXComponents.js, um sie in MDX verfügbar zu machen
  3. Wenn die Komponente übersetzbare UI-Strings enthält, führen Sie pnpm write-translations aus, um sie zu extrahieren
  4. Führen Sie pnpm translate aus, um die neuen Strings 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 in der Sidebar 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 Überschrift-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: In documentation/static/img/ platzieren und in Markdown mit /img/filename.png referenzieren
  • Downloads/PDFs: In documentation/static/ platzieren und mit /filename.pdf referenzieren
  • Pro-Locale-Assets: Wenn ein Asset lokal 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 in mindestens der Standard-Englischsprache und einer anderen Sprache, um sicherzustellen, dass die Übersetzungen korrekt angezeigt werden.