i18n接口¶

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 中查找邮件目录，并确保在 translators 中至少设置了一个空翻译目录。如果多次调用或找到多个 .mo 文件，它们的内容将合并在一起（从而使 init 可重入）。

sphinx.locale.init_console(locale_dir: str | os.PathLike[str] | None = None, catalog: str = 'sphinx') → tuple[NullTranslations, bool][源代码]¶: 初始化控制台的区域设置。

在 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)

使用这段代码，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() 帮助。

实际上，您必须：

为邮件目录选择一个名称，该名称必须是唯一的。通常，插件名的名称用于消息目录的名称。

通过 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!')

设置插件以了解其专用翻译：

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)

生成消息目录模板 *.pot 文件，通常位于 locale/ 源目录中，例如通过 Babel 生成：
```
$ pybabel extract --output=src/locale/myextension.pot src/
```

为您的插件将提供本地化的每种语言创建消息目录（*.po），例如通过 Babel ：

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

将邮件目录编译为 *.mo 文件，例如通过 Babel ：

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

通过在扩展名中添加等效行，确保在安装包时分发了消息目录文件 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

i18n接口¶

使用 i18n API 进行扩展国际化（i18n）和本地化（l10n）¶

使用 i18n API 进行扩展国际化（`i18n`）和本地化（`l10n`）¶