Übersetzungs-Abläufe

Die Übersetzung der Dokumentation von darktable wird mit Weblate ausgeführt.

🔗Übersicht über den Aufbau und Datenaustausch für die Übersetzungen mittels Weblate

In Kürze:

  1. Das Handbuch wird primär auf Englisch in den .md-Dateien in content/*.md gepflegt
  2. Von da aus wird eine POT Datei (po/content.pot) mit allen übersetzbaren Zeichenketten generiert.
  3. Weblate pflegt für jede übersetzte Sprache eine einzelne PO-Datei (po/content.{lang}.po), die die übersetzten Zeichenketten entält.
  4. Bei der Veröffentlichung des Handbuches werden .md Dateien für jede aktivierte Übersetzung mittels generate-translations.sh generiert. hugo rendert daraus dann die .html Dateien sowie den EPUB und PDF Varianten.

🔗GitHub zu Weblate: Synchronisierung der übersetzbaren Zeichenktten

  1. Die originalen Englischen Dateien (content/*.md) werden mittels Pull Request aktualisiert (siehe Arbeitsablauf).

  2. Eine nächtliche GitHub Aktion updatet die POT Datei (po/content.pot), die alle übersetzbaren Zeichenketten enthält, mit generate-translations.sh --no-translations. Beachte: Dieses Skript aktualisiert prinzipiell POT und PO Dateien, wir committen die generierten PO Dateien aber nicht ins Repository. Diese werden in unserem Setup nur durch Weblate gepflegt, um merge conflicts zu vermeiden.

  3. Weblate lädt die aktualisierte POT-Datei (ausgelöst über die Weblate GitHub App) und befüllt inern die PO Dateien jeder Sprache mit neuen/aktualisierten Zeichenketten.

  4. Weblate committed die Änderungen auf Github indem ein Pull Request eröffnet wird.

  5. Das Pull Request wird nach Überprüfung gemerged.

🔗Weblate zu GitHub: Übersetzungs-Synchronisation

  1. Übersetzungen werden auf Weblate gepflegt. Siehe Übersetzungs-Leitfaden.

  2. Weblate updatet intern die PO Dateien jeder Sprache und committed diese zu Github mittels Pull Request. Um die Anzahl der Pull-Requests niedrig zu halten werden für ein Pull-Request immer mehrere Änderungen gesammelt.

🔗Generieren von übersetzten Dateien

Bei der Veröffentlichung auf docs.darktable.org werden die übersetzten .md-Dateien aus den PO Dateien in /po/ mit generate-translations.sh --no-update generiert. Dieses ist für die automatisch generierten GitHub Pages deaktiviert.

🔗Eine neue Sprache zu Hugo hinzufügen

  1. Füge eine neue Sprache zu Weblate hinzu. Siehe dazu auch Weblates Dokumentation. Stelle sicher, dass die dadurch neu generierte PO Datei ins dtdocs Repository committed wird.

  2. Lokalisiere die Zeile languages: in den Dateien config.yaml und config-pdf.yaml.

  3. Füge die Sprache, die du übersetzen willst, hinzu. Für Englisch sieht das so aus:

      en-us:
    title: darktable user manual
    weight: 1

🔗Aktivieren und Deaktivieren von übersetzten Sprachen

Die aktivierten Sprachen werden an zwei Stellen gepflegt, die idealerweise manuell synchron gehalten werden:

  • config.yaml undconfig-pdf.yaml — die Konfiguration für hugo. Hier gelistete Sprachen bekommen ihren eigenen Abschnitt in der Website/PDF.

  • disable-languages - Eine Liste von Sprachcodes im Hauptverzeichnis des dtdocs repository. generate-translations.sh prüft diese Datei und überspringt für die aufgezählten Sprachen .{lang}.md-Dateien, selbst wenn für die jeweilige Sprache eine PO Datei vorliegt.

Der Sprachumschalter listet nur Sprachen, wenn tatsächlich übersetzte .{lang}.md-Dateien für die aktuelle Seite vorliegen. Er benutzt Hugos .IsTranslated und .Translations Variablen, welche die tatsächlich vorhandenen Dateien enthalten und nicht die Einträge in config.yaml. Eine Sprache die in config.yaml enthalten ist aber in disable-languages gelistet ist, wird aher nicht im Sprachumschalter auftauchen, da keine übersetzten Dateien für sie generiert werden.

Um eine Sprache zu aktivieren muss sie in config.yaml, config-pdf.yaml undconfig-epub.yaml enthalten sein und darf nicht in disable-languages gelistet sein.

Um eine Sprache zu deaktivieren, sollte sie in disable-languages enthalten sein. Die einträge in config.yaml, config-pdf.yaml und config-epub.yaml können prinzipiell erhalten bleiben falls die Sprache in der Zukunft reaktiviert werden soll.

🔗Übersetzung von Webseiten-, ePub- und PDF-Zeichenfolgen

Es gibt drei Themen für die Dokumentation: Eine für die HTML-Website, eine für EPUB und eine für das PDF. Jede hat eine einige UI-Strings (z.B. “Table of Contents”, “Copyright”, “Search”), die manuell übersetzt werden müssen - diese Strings werden nicht über Weblate verwaltet.

  1. Gehe zu themes/hugo-darktable-docs-theme/i18n.

  2. Kopiere den Inhalt der Datei en.yaml und benenne die neue mit einem Sprach-Code (z.B. de-de.yaml,fr-fr.yaml)

  3. Übersetze den Inhalt der neuen yaml Datei.

  4. Checke die übersetzte yaml-Datei in git, übertrage sie auf github und öffne einen Pull Request damit deine Änderungen angenommen werden können.

  5. Wiederhole dies für themes/hugo-darktable-docs-epub-theme/i18n und themes/hugo-darktable-docs-pdf-theme/i18n. Diese Themes benutzen kurze Sprachcodes, (z.B. de.yaml) ggf. mit Unterstrich für lokale Varianten (e.g. pt_br.yaml).

🔗generate-translations.sh

Dieses Skript wird von der nächtlichen GitHub Aktion benutzt und kann auch lokal zum Debugging ausgeführt werden, oder um die Übersetzungsdateien manuell zu aktualisieren.

Das Skript ist ein Wrapper um po4a, um das Zusammenspiel zwischen den originalen .md Dateien und den Übersetzungen zu orchestrieren. Das Skript liest die disable-languages-Datei im Basisverzeichnis des Repositories, filtert deaktivierte Sprachen aus, baut eine temporäre po4a config-Datei, die alle content/*/*.md-Dateien enthält, und führt dann damitpo4a $1 --verbose $po4a_conf aus. Es erfordert eines dieser drei Argumente:

--no-translations
Generiert POT- und PO-Dateien (po/content.pot und po/content.{lang}.po)) aus den ursprünglichen .md-Dateien (content/*.md). Erzeugt keine übersetzten .md-Dateien. Neue oder geänderte Zeichenketten aus den Quelldateien werden in die POT/PO-Dateien gezogen, jedoch werden keine *.{lang}.md-Dateien erzeugt. Dies wird nach Updates der englischen Quelldateien verwendet, um die POT- und PO-Dateien für Weblate vorzubereiten.
--no-update
Generiert die übersetzten Markdown-Dateien aus den vorhandenen PO-Dateien, ohne die POT/PO-Dateien zu aktualisieren. Dies bedeutet, dass die Quelldateien (content/*.md) nicht wieder gelesen werden; bestehende Übersetzungen werden direkt in lokalisierte .{lang}.md Dateien übersetzt.
-rm-Übersetzungen
Entfernt die generierten übersetzten Dateien. po4a löscht die lokalisierten *.{lang}.md Ausgabedateien, die zuvor von -no-update erstellt wurden. Die PO/POT-Dateien bleiben unberührt.

translations