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][ソース]¶: 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 | os.PathLike[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 を利用して、拡張機能内のメッセージを翻訳できます。

from pathlib import Path
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(__file__).resolve().parent
    locale_dir = 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() にも説明されています。

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

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

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!')

専用の翻訳を認識するように拡張機能を設定します。

src/__init__.py¶

def setup(app):
    package_dir = Path(__file__).resolve().parent
    locale_dir = package_dir / 'locales'
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

メッセージカタログテンプレートファイル *.pot を作成します、通常 locale/ ソースディレクトリで、例えば以下を利用 Babel:
```
$ pybabel extract --output=src/locale/myextension.pot src/
```

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

各々の言語のメッセージカタログを手動で翻訳します
メッセージカタログを *.mo へコンパイルします、例えば以下 Babel を利用:
```
$ pybabel compile --directory=src/locale --domain=myextension
```
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

i18n API¶

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

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