Dokumentation mit Sphinx übersetzen

Sphinx ist ein Tool zur Erstellung schöner Dokumentationen. Es verwendet eine einfache reStructuredText-Syntax und kann Ausgaben in vielen Formaten erzeugen. Falls Sie nach einem Beispiel suchen, diese Dokumentation wurde ebenfalls mit Sphinx erstellt. Ein sehr nützlicher Begleiter für die Verwendung von Sphinx ist der Dienst Read the Docs, der Ihre Dokumentation kostenlos erstellt und veröffentlicht.

Ich werde mich nicht auf das Schreiben der Dokumentation selbst konzentrieren. Wenn Sie dabei Hilfe benötigen, folgen Sie einfach den Anweisungen auf der Sphinx-Website. Sobald Sie die Dokumentation fertig haben, ist das Übersetzen recht einfach, da Sphinx dies unterstützt und es in Internationalization sehr gut beschrieben ist. Es ist eine Frage von ein paar Konfigurationsanweisungen und dem Aufruf des sphinx-intl-Tools.

Wenn Sie den „Read the Docs“-Dienst nutzen, können Sie mit der Erstellung der übersetzten Dokumentation auf Read the Docs beginnen. Deren Localization and Internationalization deckt so ziemlich alles ab, was Sie brauchen – ein weiteres Projekt erstellen, dessen Sprache festlegen und es vom Hauptprojekt als Übersetzung verlinken.

Jetzt müssen Sie nur noch den Inhalt der Dokumentation übersetzen. Sphinx generiert PO-Dateien für jedes Verzeichnis oder jede Datei der obersten Ebene, was zu einer großen Anzahl von zu übersetzenden Dateien führen kann (abhängig von den gettext_compact-Einstellungen). Sie können die Datei index.po als erste Komponente in Weblate importieren und dann die Erweiterung Komponentenerkennung so konfigurieren, dass alle anderen Dateien automatisch erkannt werden.

Komponentenkonfiguration

Komponentenname

Documentation

Dateimaske

docs/locales/*/LC_MESSAGES/index.po

Vorlage für neue Übersetzungen

docs/locales/index.pot

Dateiformat

gettext PO-Datei

Übersetzungsmarkierungen

rst-text
Konfiguration der Komponentenerkennung

Regulärer Ausdruck zum Abgleich von Übersetzungsdateien

docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po

Anpassen des Komponentennamens

Documentation: {{ component|title }}

Definition der Basisdatei für neue Übersetzungen

docs/locales/{{ component }}.pot

Hinweis

Möchten Sie, dass Sphinx nur eine einzige PO-Datei erzeugt? Seit Sphinx 3.3.0 können Sie dies erreichen:

gettext_compact = "docs"

Es gibt mehrere Dokumentationsprojekte, die nach diesem Konzept übersetzt werden: