i18n API

sphinx.locale.init(locale_dirs: Iterable[str | os.PathLike[str] | None], language: str | None, catalog: str = 'sphinx', namespace: str = 'general') → tuple[NullTranslations, bool][source]

Suchen Sie nach Nachrichten-Katalogen in locale_dirs und stellen Sie sicher, dass mindestens ein NullTranslations-Katalog in translators gesetzt ist. Wenn die Funktion mehrmals aufgerufen wird oder mehrere .mo-Dateien gefunden werden, werden deren Inhalte zusammengeführt (wodurch init reentrant wird).

sphinx.locale.init_console(locale_dir: str | os.PathLike[str] | None = None, catalog: str = 'sphinx') → tuple[NullTranslations, bool][source]

Initialisiert die Locale für die Konsole.

Hinzugefügt in Version 1.8.

sphinx.locale.get_translation(catalog: str, namespace: str = 'general') → Callable[[str], str][source]

Rufen Sie eine Übersetzungsfunktion basierend auf dem *Katalog* und dem *Namespace* ab.

Die Erweiterung kann diese API verwenden, um die Nachrichten der Erweiterung zu übersetzen

from pathlib import Path
from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
_ = get_translation(MESSAGE_CATALOG_NAME)
text = _('Hello Sphinx!')


def setup(app):
    package_dir = Path(__file__).resolve().parent
    locale_dir = package_dir / 'locales'
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

Mit diesem Code sucht Sphinx nach einem Nachrichten-Katalog in ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo. Die language wird für die Suche verwendet.

Hinzugefügt in Version 1.8.

sphinx.locale._(message: str) → str

Übersetzungsfunktion für Nachrichten in der Dokumentation (Menü, Labels, Themes usw.). Diese Funktion folgt der Einstellung language.

sphinx.locale.__(message: str) → str

Übersetzungsfunktion für Konsolenmeldungen. Diese Funktion folgt den Locale-Einstellungen (LC_ALL, LC_MESSAGES usw.).

Internationalisierung (i18n) und Lokalisierung (l10n) von Erweiterungen mit der i18n API

Hinzugefügt in Version 1.8.

Eine Erweiterung kann natürlich Nachrichtenübersetzungen enthalten. Dies wird kurz in der Hilfe zu sphinx.locale.get_translation() zusammengefasst.

In der Praxis müssen Sie

  1. Wählen Sie einen Namen für Ihren Nachrichten-Katalog, der eindeutig sein muss. Normalerweise wird der Name Ihrer Erweiterung für den Namen des Nachrichten-Katalogs verwendet.

  2. Markieren Sie in Ihren Quelltexten alle Nachrichten als übersetzbar, über die Funktion sphinx.locale.get_translation(), üblicherweise umbenannt in _(), z.B.

    src/__init__.py
    from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = 'myextension'
_ = get_translation(MESSAGE_CATALOG_NAME)

translated_text = _('Hello Sphinx!')

  3. Richten Sie Ihre Erweiterung so ein, dass sie ihre dedizierten Übersetzungen kennt

    src/__init__.py
    def setup(app):
    package_dir = Path(__file__).resolve().parent
    locale_dir = package_dir / 'locales'
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

  4. Generieren Sie eine Vorlagendatei für Nachrichten-Kataloge (*.pot), normalerweise im Quellverzeichnis locale/, zum Beispiel über Babel

    $ pybabel extract --output=src/locale/myextension.pot src/

  5. Erstellen Sie Nachrichten-Kataloge (*.po) für jede Sprache, für die Ihre Erweiterung eine Lokalisierung anbieten wird, zum Beispiel über Babel

    $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR

  6. Übersetzen Sie Nachrichten-Kataloge für jede Sprache manuell

  7. Kompilieren Sie Nachrichten-Kataloge in *.mo-Dateien, zum Beispiel über Babel

    $ pybabel compile --directory=src/locale --domain=myextension

  8. Stellen Sie sicher, dass Nachrichten-Katalog-Dateien beim Installieren Ihres Pakets verteilt werden, indem Sie eine entsprechende Zeile in Ihre Erweiterung MANIFEST.in einfügen

    MANIFEST.in
    recursive-include src *.pot *.po *.mo

Wenn sich die Nachrichten in Ihrer Erweiterung geändert haben, müssen Sie auch die Vorlagendatei für Nachrichten-Kataloge und die Nachrichten-Kataloge aktualisieren, zum Beispiel über Babel

$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale