i18n API

sphinx.locale.init(locale_dirs: List[str], language: str, catalog: str = 'sphinx', namespace: str = 'general') → Tuple[gettext.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, catalog: str) → Tuple[gettext.NullTranslations, bool][ソース]

コンソール向けにロケールを初期化します。

バージョン 1.8 で追加.

sphinx.locale.get_translation(catalog: str, namespace: str = 'general') → Callable[ソース]

catalognamespace に基づいて、翻訳関数を取得します。

この 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)

この例では、Sphinx は拡張用のメッセージカタログを ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo から読み込みます。ファイルの検索には language が利用されます。

バージョン 1.8 で追加.

sphinx.locale._(message: str, *args: Any)str

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

sphinx.locale.__(message: str, *args: Any)str

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

i18n API を用いた拡張機能の国際化(i18n)と地域化(l10n)

バージョン 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. Set up your extension to be aware of its dedicated translations:

    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