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

sphinx.locale.init_console(locale_dir: 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 获取一个翻译函数.

该扩展可以使用此 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 搜索消息目录.:confval:language 用于搜索.

Added in version 1.8.

sphinx.locale._(message: str) → str¶: 文档消息的翻译功能（菜单、标签、主题等）.此功能遵循 语言 设置.

sphinx.locale.__(message: str) → str¶: 控制台消息的翻译函数此函数遵循区域设置（LC_ALL, LC_MESSAGES 等）.

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

Added in version 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.abspath(path.dirname(__file__))
    locale_dir = os.path.join(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 API¶

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

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