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]

在 locale_dirs 中尋找訊息目錄，並確保在 translators 中至少設定了一個 NullTranslations 目錄。如果多次呼叫，或找到多個 .mo 檔案，它們的內容將合併在一起 (因此使 init 成為可重入的)。

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

初始化主控台的語系。

在 1.8 版本中新增。

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

根據 catalog 和 namespace 取得翻譯函式。

擴充套件可以使用此 API 來翻譯擴充套件上的訊息

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)

透過此程式碼，sphinx 會從 ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo 搜尋訊息目錄。language 用於搜尋。

在 1.8 版本中新增。

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

用於文件訊息 (選單、標籤、主題等等) 的翻譯函式。此函式遵循 language 設定。

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

用於主控台訊息的翻譯函式。此函式遵循語系設定 (LC_ALL、LC_MESSAGES 等等)。

擴充套件國際化 (i18n) 與本地化 (l10n) 使用 i18n API

在 1.8 版本中新增。

擴充套件可能自然而然地帶有訊息翻譯。這在 sphinx.locale.get_translation() 說明中簡要概述。

實際上，您必須

  1. 為您的訊息目錄選擇一個名稱，該名稱必須是唯一的。通常，您的擴充套件名稱會用作訊息目錄的名稱。

  2. 在您的擴充套件原始碼中，將所有訊息標記為可翻譯的，透過 sphinx.locale.get_translation() 函式，通常重新命名為 _()，例如

    src/__init__.py
    from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = 'myextension'
_ = get_translation(MESSAGE_CATALOG_NAME)

translated_text = _('Hello Sphinx!')

  3. 設定您的擴充套件以使其知道其專用的翻譯

    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. 產生訊息目錄範本 *.pot 檔案，通常在 locale/ 原始碼目錄中，例如透過 Babel

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

  5. 為您的擴充套件將提供的本地化服務的每種語言建立訊息目錄 (*.po)，例如透過 Babel

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

  6. 手動翻譯每種語言的訊息目錄

  7. 將訊息目錄編譯成 *.mo 檔案，例如透過 Babel

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

  8. 確保在安裝您的套件時，訊息目錄檔案會被分發，方法是在您的擴充套件 MANIFEST.in 中加入等效的行

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

當您的擴充套件上的訊息已變更時，您也需要更新訊息目錄範本和訊息目錄，例如透過 Babel

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