i18n API

sphinx.locale.init(locale_dirs, language, catalog='sphinx', namespace='general')[源代码]

在 locale_dirs 中查找消息目录, 并 确保 在 translators 中至少设置了NullTranslations目录.如果多次调用或者找到几个 .mo 文件, 它们的内容将合并在一起(从而使 init 可重入).

sphinx.locale.init_console(locale_dir, catalog)[源代码]

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

1.8 新版功能.

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

获取基于 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 = path.abspath(path.dirname(__file__))
    locale_dir = os.path.join(package_dir, 'locales')
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

With this code, sphinx searches a message catalog from ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The language is used for the searching.

1.8 新版功能.

sphinx.locale._(message, *args)

文档上的消息的翻译功能(菜单, 标签, 主题等). 该函数如下 language 设置.

sphinx.locale.__(message, *args)

控制台消息的翻译功能此功能遵循区域设置(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!')

  1. 设置您的扩展程序以了解其专用翻译:

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)

  1. 生成消息目录模板 *.pot 文件, 通常在 locale/ 源目录中, 例如通过 Babel:

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

  2. 为您的扩展将提供本地化的每种语言创建消息目录(*.po), 例如通过 Babel:

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

  3. 手动翻译每种语言的消息目录

  4. 将消息目录编译为 *.mo 文件, 例如通过 Babel:

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

  5. 通过在扩展名 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