Internationalisierung

Hinzugefügt in Version 1.1.

Ergänzend zu Übersetzungen, die für von Sphinx generierte Nachrichten wie Navigationsleisten bereitgestellt werden, bietet Sphinx Mechanismen zur Erleichterung der Übersetzung von *Dokumenten*. Einzelheiten zur Konfiguration finden Sie in den Optionen für die Internationalisierung.

../../_images/translation.svg

Visualisierung des Arbeitsablaufs von Übersetzungen in Sphinx. (Die Abbildung wurde von plantuml erstellt.)

Details zur Internationalisierung von Sphinx

gettext [1] ist ein etablierter Standard für Internationalisierung und Lokalisierung. Er ordnet Nachrichten in einem Programm einer übersetzten Zeichenkette zu. Sphinx nutzt diese Einrichtungen, um ganze Dokumente zu übersetzen.

Zunächst müssen die Projektbetreuer alle übersetzbaren Zeichenketten (auch als *Nachrichten* bezeichnet) sammeln, um sie den Übersetzern bekannt zu machen. Sphinx extrahiert diese durch Aufruf von sphinx-build -M gettext.

Jedes einzelne Element im Doctree wird zu einer einzigen Nachricht, was dazu führt, dass Listen in verschiedene Abschnitte aufgeteilt werden, während große Absätze so grob wie im Originaldokument bleiben. Dies ermöglicht nahtlose Dokumentenaktualisierungen und bietet dennoch etwas Kontext für Übersetzer in Freitextpassagen. Es liegt in der Verantwortung des Betreuers, zu große Absätze aufzuteilen, da es keine sinnvolle automatisierte Möglichkeit dafür gibt.

Nachdem Sphinx den MessageCatalogBuilder erfolgreich ausgeführt hat, finden Sie eine Sammlung von .pot-Dateien in Ihrem Ausgabeverzeichnis. Dies sind **Katalogvorlagen** und enthalten ausschließlich Nachrichten in Ihrer Originalsprache.

Sie können an Übersetzer geliefert werden, die sie in .po-Dateien umwandeln – sogenannte **Nachrichtenkataloge** –, die eine Zuordnung von den Originalnachrichten zu fremdsprachigen Zeichenketten enthalten.

gettext kompiliert sie aus Effizienzgründen mithilfe von msgfmt in ein Binärformat, das als **Binärdateien** bekannt ist. Wenn Sie diese Dateien mit locale_dirs für Ihre language auffindbar machen, erkennt Sphinx sie automatisch.

Ein Beispiel: Sie haben ein Dokument usage.rst in Ihrem Sphinx-Projekt. Der gettext-Builder platziert seine Nachrichten in usage.pot. Stellen Sie sich vor, Sie haben spanische Übersetzungen [2], die in usage.po gespeichert sind – damit Ihre Builds übersetzt werden können, müssen Sie die folgenden Anweisungen befolgen:

  • Kompilieren Sie Ihren Nachrichtenkatalog in ein lokales Verzeichnis, z. B. locale, sodass er in ./locale/es/LC_MESSAGES/usage.mo in Ihrem Quellverzeichnis landet (wobei es der Sprachcode für Spanisch ist).

    msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

  • Setzen Sie locale_dirs auf ["locale/"].

  • Setzen Sie language auf es (auch möglich über -D).

  • Führen Sie Ihren gewünschten Build aus.

Um sich vor Fehlern zu schützen, wird eine Warnung ausgegeben, wenn Querverweise im übersetzten Absatz nicht mit denen im Original übereinstimmen. Dies kann global über die Konfigurationsvariable suppress_warnings ausgeschaltet werden. Alternativ können Sie es für eine einzelne Nachricht ausschalten, indem Sie die Nachricht mit #noqa beenden, wie hier:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

(Schreiben Sie \#noqa, falls Sie "#noqa" buchstäblich im Text haben möchten. Dies gilt nicht für Codeblöcke, wo #noqa ignoriert wird, da Codeblöcke ohnehin keine Referenzen enthalten.)

Hinzugefügt in Version 4.5: Der Mechanismus #noqa.

Übersetzen mit sphinx-intl

Schnellübersicht

sphinx-intl ist ein nützliches Werkzeug zur Arbeit mit dem Sphinx-Übersetzungsfluss. Dieser Abschnitt beschreibt eine einfache Möglichkeit, mit sphinx-intl zu übersetzen.

  1. Installieren Sie sphinx-intl.

    $ pip install sphinx-intl

  2. Fügen Sie Konfigurationen zu conf.py hinzu.

    locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.

    Dieser Fallstudien-Fall geht davon aus, dass BUILDDIR auf _build gesetzt ist, locale_dirs auf locale/ gesetzt ist und gettext_compact auf False gesetzt ist (die Sphinx-Dokumentation ist bereits so konfiguriert).

  3. Extrahieren Sie übersetzbare Nachrichten in POT-Dateien.

    $ make gettext

    Die generierten POT-Dateien werden im Verzeichnis _build/gettext abgelegt. Wenn Sie die Ausgabe über die Optionen für die Internationalisierung hinaus anpassen möchten, kann die Standardvorlage für POT-Dateien durch eine benutzerdefinierte message.pot.jinja-Datei ersetzt werden, die in einem beliebigen Verzeichnis in templates_path abgelegt ist.

  4. Generieren Sie PO-Dateien.

    Wir verwenden die im vorherigen Schritt generierten POT-Dateien.

    $ sphinx-intl update -p _build/gettext -l de -l ja

    Nach Abschluss werden die generierten PO-Dateien in den folgenden Verzeichnissen abgelegt:

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. Übersetzen Sie PO-Dateien.

    Wie oben erwähnt, befinden sich diese im Verzeichnis ./locale/<lang>/LC_MESSAGES. Ein Beispiel für eine solche Datei, von Sphinx, builders.po, ist unten angegeben.

    # a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

    Ein anderer Fall: msgid ist mehrzeiliger Text und enthält reStructuredText-Syntax.

    # 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

    Bitte achten Sie darauf, die reStructuredText-Notation nicht zu beschädigen. Die meisten PO-Editoren helfen Ihnen dabei.

  6. Erstellen Sie das übersetzte Dokument.

    Sie benötigen einen language-Parameter in conf.py oder Sie können den Parameter auch in der Befehlszeile angeben.

    Für BSD/GNU make, führen Sie aus:

    $ make -e SPHINXOPTS="-D language='de'" html

    Für Windows cmd.exe, führen Sie aus:

    > set SPHINXOPTS=-D language=de
> .\make.bat html

    Für PowerShell, führen Sie aus:

    PS> Set-Item env:SPHINXOPTS "-D language=de"
PS> .\make.bat html

Herzlichen Glückwunsch! Sie haben die übersetzte Dokumentation im Verzeichnis _build/html gefunden.

Hinzugefügt in Version 1.3: sphinx-build, das vom make-Befehl aufgerufen wird, kompiliert PO-Dateien in MO-Dateien.

Wenn Sie Version 1.2.x oder früher verwenden, rufen Sie bitte den Befehl sphinx-intl build vor dem Befehl make auf.

Übersetzung

Aktualisieren Sie Ihre PO-Dateien mit neuen POT-Dateien

Wenn ein Dokument aktualisiert wird, ist es notwendig, aktualisierte POT-Dateien zu generieren und die Unterschiede auf die übersetzten PO-Dateien anzuwenden. Um die Aktualisierungen aus einer POT-Datei auf die PO-Datei anzuwenden, verwenden Sie den Befehl sphinx-intl update.

$ sphinx-intl update -p _build/gettext

Verwendung des Transifex-Dienstes für die Teamübersetzung

Transifex ist einer von mehreren Diensten, die eine kollaborative Übersetzung über eine Web-Oberfläche ermöglichen. Es verfügt über einen raffinierten Go-basierten Befehlszeilenclient, der das Abrufen und Hochladen von Übersetzungen erleichtert.

  1. Installieren Sie das Transifex CLI-Tool.

    Sie benötigen das Befehlszeilenwerkzeug tx zum Hochladen von Ressourcen (POT-Dateien). Der offizielle Installationsprozess platziert die tx-Binärdatei im aktuellen Verzeichnis zusammen mit einer README- und einer LICENSE-Datei und fügt das aktuelle Verzeichnis zu $PATH hinzu.

    $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

    Siehe auch

    Dokumentation des Transifex Clients

  2. Erstellen Sie Ihr Transifex-Konto und erstellen Sie ein neues Projekt und eine Organisation für Ihr Dokument.

    Derzeit erlaubt Transifex einem Übersetzungsprojekt nicht, mehr als eine Version des Dokuments zu haben, daher ist es besser, eine Versionsnummer in Ihren Projektnamen aufzunehmen.

    Zum Beispiel

    Organisations-ID:

    sphinx-document

    Projekt-ID:

    sphinx-document-test_1_0

    Projekt-URL:

    https://www.transifex.com/projects/p/sphinx-document-test_1_0/

  3. Erstellen Sie ein API-Token für die Verwendung in der Befehlszeile.

    Rufen Sie Ihre Transifex API-Token-Seite auf und generieren Sie ein Token. Kopieren Sie das generierte Token jetzt, da Sie es später nicht mehr sehen können.

  4. Stellen Sie Ihr Transifex API-Token in der Benutzerkonfigurationsdatei $HOME/.transifexrc ein.

    [https://app.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = paste_your_api_token_here

  5. Alternativ können Sie Ihr Transifex API-Token als Umgebungsvariable TX_TOKEN speichern, die von tx erkannt und verwendet wird.

    $ export TX_TOKEN=paste_your_api_token_here

  6. Erstellen Sie die Konfigurationsdatei des Projekts für den tx-Befehl.

    Dieser Vorgang erstellt .tx/config im aktuellen Verzeichnis.

    $ cd /your/document/root
$ tx init

Successful creation of '.tx/config' file

  7. Laden Sie POT-Dateien zum Transifex-Dienst hoch.

    Registrieren Sie POT-Dateien in der .tx/config-Datei mithilfe von sphinx-intl update-txconfig-resources und passen Sie den Wert von --pot-dir an das Verzeichnis der POT-Dateien Ihres Projekts an.

    $ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
  --transifex-organization-name=sphinx-document \
  --transifex-project-name=sphinx-document-test_1_0

    Sie können die Umgebungsvariablen SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME und SPHINXINTL_TRANSIFEX_PROJECT_NAME anstelle der entsprechenden Befehlszeilenargumente verwenden.

    Siehe auch

    Dokumentation von sphinx-intl update-txconfig-resources

    und laden Sie POT-Dateien hoch

    $ tx push -s
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pushing source files

sphinx-document-test_1_0.builders - Uploading file
sphinx-document-test_1_0.builders - Done

  8. Leiten Sie die Übersetzung auf Transifex weiter.

  9. Ziehen Sie übersetzte PO-Dateien herunter und erstellen Sie übersetzte HTML-Dateien.

    Rufen Sie übersetzte Kataloge ab und erstellen Sie MO-Dateien. Zum Beispiel, um MO-Dateien für Deutsch (de) zu erstellen:

    $ cd /your/document/root
$ tx pull -l de
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pulling files

sphinx-document-test_1_0.builders [de] - Pulling file
sphinx-document-test_1_0.builders [de] - Creating download job
sphinx-document-test_1_0.builders [de] - Done

    Rufen Sie make html (für BSD/GNU make) auf und übergeben Sie den Sprachcode.

    $ make -e SPHINXOPTS="-D language='de'" html

Das war's!

Tipp

Lokale und Transifex-Übersetzung

Wenn Sie alle PO-Dateien einer Sprache pushen möchten, können Sie dies mit dem Befehl tx push -t tun. Vorsicht! Diese Operation überschreibt Übersetzungen in Transifex.

Mit anderen Worten, wenn Sie sowohl die Service- als auch die lokalen PO-Dateien aktualisiert haben, würde es viel Zeit und Mühe kosten, sie zu integrieren.

Verwendung des Weblate-Dienstes für die Teamübersetzung

Lesen Sie mehr in der Dokumentation von Weblate.

Beitragen zur Übersetzung der Sphinx-Referenz

Der empfohlene Weg für neue Mitwirkende, die Sphinx-Referenz zu übersetzen, ist, dem Übersetzungsteam auf Transifex beizutreten.

Es gibt eine Sphinx-Übersetzungsseite für die Sphinx (master) Dokumentation.

  1. Melden Sie sich beim Transifex-Dienst an.

  2. Gehen Sie zum Übersetzungsprojekt „Sphinx’s documentation“.

  3. Klicken Sie auf Sprache anfordern und füllen Sie das Formular aus.

  4. Warten Sie auf die Annahme durch die Transifex-Sphinx-Übersetzungsbetreuer.

  5. (Nach Annahme) Übersetzen Sie auf Transifex.

Details finden Sie hier: https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

Übersetzungsfortschritt und Statistiken

Hinzugefügt in Version 7.1.0.

Während des Rendering-Prozesses markiert Sphinx jeden übersetzbaren Knoten mit einem Attribut translated, das angibt, ob eine Übersetzung für den Text in diesem Knoten gefunden wurde.

Der Konfigurationswert translation_progress_classes kann verwendet werden, um jedem Element eine Klasse hinzuzufügen, abhängig vom Wert des Attributs translated.

Die Ersetzung |translation progress| kann verwendet werden, um den Prozentsatz der übersetzten Knoten pro Dokument anzuzeigen.

Fußnoten