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][源代码]

在以下位置查找邮件目录 locale_dirs 和 ensure 中至少设置了一个NullTranslations目录 translators 。如果多次调用或多次调用 .mo 找到文件，将其内容合并在一起(从而使 init 重入)。

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

初始化控制台的区域设置。

Added in version 1.8.

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

属性获取翻译函数。 catalog 和 namespace 。

扩展名可以使用此接口翻译扩展名上的消息：：

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)

使用此代码，Shinx将搜索来自 ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo 。这个 language 用于搜索。

Added in version 1.8.

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

文档(菜单、标签、主题等)消息的翻译功能。此函数如下 language 布景。

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

控制台消息的翻译功能此功能遵循区域设置 (LC_ALL ， LC_MESSAGES 等等)。

扩展国际化 (i18n ）和本地化 (l10n ）使用i18n API

Added in version 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