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][source]

locale_dirs でメッセージカタログを探し、translators に少なくとも NullTranslations カタログが設定されていることを*保証*します。複数回呼び出された場合、または複数の .mo ファイルが見つかった場合、その内容はマージされます（そのため、init は再入可能になります）。

sphinx.locale.init_console(locale_dir: str | None = None, catalog: str = 'sphinx') → tuple[NullTranslations, bool][source]

コンソール用のロケールを初期化します。

バージョン 1.8 で追加されました。

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

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 は検索に使用されます。

バージョン 1.8 で追加されました。

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

ドキュメント（メニュー、ラベル、テーマなど）のメッセージの翻訳関数。この関数は language 設定に従います。

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

コンソールメッセージの翻訳関数。この関数はロケール設定（LC_ALL、LC_MESSAGES など）に従います。

拡張機能の国際化（i18n）とローカリゼーション（l10n）i18n API を使用

バージョン 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!')

  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. 通常は locale/ ソースディレクトリにあるメッセージカタログテンプレート *.pot ファイルを生成します。例： Babel

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

  5. 拡張機能がローカリゼーションを提供する各言語のメッセージカタログ（*.po）を作成します。例： Babel

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

  6. 各言語のメッセージカタログを手動で翻訳します。

  7. メッセージカタログを *.mo ファイルにコンパイルします。例： Babel

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

  8. パッケージのインストール時にメッセージカタログファイルが配布されるようにします。拡張機能の 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