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 | 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 来翻译扩展上的消息

import os
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 = os.path.abspath(os.path.dirname(__file__))
    locale_dir = os.path.join(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 API 进行扩展国际化 (i18n) 和本地化 (l10n)

在版本 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.abspath(path.dirname(__file__))
    locale_dir = os.path.join(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