i18n API

sphinx.locale.init(locale_dirs: Iterable[str | None], language: str | None, catalog: str = 'sphinx', namespace: str = 'general') → tuple[NullTranslations, bool][ソース]

Look for message catalogs in locale_dirs and ensure that there is at least a NullTranslations catalog set in translators. If called multiple times or if several .mo files are found, their contents are merged together (thus making init reentrant).

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 から読み込みます。ファイルの検索には language が利用されます。

Added in version 1.8.

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

ドキュメント用の翻訳関数です。メニュー、ラベル、テーマなどでも利用されます。この関数は language の設定に基づいてメッセージを翻訳します。

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

コンソール用の翻訳関数です。この関数はロケール設定(LC_ALL 、 LC_MESSAGE など)に基づいてメッセージを翻訳します。

Extension internationalization (i18n) and localization (l10n) using i18n API

Added in version 1.8.

拡張機能向けにメッセージ翻訳機能が提供されています。利用方法は sphinx.locale.get_translation() にも説明されています。

以下の手順で利用できます。

  1. メッセージカタログの名前を決めます。名前はユニークである必要があります。拡張機能の名前を利用すると良いでしょう。

  2. Mark in your extension sources all messages as translatable, via sphinx.locale.get_translation() function, usually renamed _(), e.g.:

    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. Generate message catalog template *.pot file, usually in locale/ source directory, for example via Babel:

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

  5. Create message catalogs (*.po) for each language which your extension will provide localization, for example via Babel:

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

  6. Translate message catalogs for each language manually

  7. Compile message catalogs into *.mo files, for example via Babel:

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

  8. Ensure that message catalog files are distributed when your package will be installed, by adding equivalent line in your extension MANIFEST.in:

    MANIFEST.in
    recursive-include src *.pot *.po *.mo

When the messages on your extension has been changed, you need to also update message catalog template and message catalogs, for example via Babel:

$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale