コンテンツにスキップ

pytilpack.i18n

必要なextra

pip install pytilpack[babel] (for middleware features)

pytilpack.i18n

国際化(i18n)関連。

I18nState(locale_dir, domain='messages', locales=None, default_locale='en', fallback=True)

i18n状態を保持するクラス。app単位でインスタンスを作成する。

ソースコード位置： pytilpack/i18n.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def __init__(
    self,
    locale_dir: str | pathlib.Path,
    domain: str = "messages",
    locales: list[str] | None = None,
    default_locale: str = "en",
    fallback: bool = True,
) -> None:
    self.locale_dir = pathlib.Path(locale_dir)
    self.domain = domain
    self.default_locale = default_locale
    self.fallback = fallback
    # サポートロケール: 指定がなければlocale_dir内のディレクトリを自動検出
    if locales is not None:
        self.supported_locales = list(locales)
    else:
        self.supported_locales = _detect_locales(self.locale_dir)
    # 翻訳カタログを読み込んでキャッシュ
    self.translations: dict[str, gettext.GNUTranslations | gettext.NullTranslations] = {}
    for locale in self.supported_locales:
        self.translations[locale] = _load_translations(self.locale_dir, self.domain, locale, self.fallback)
    logger.info(f"i18n初期化完了: domain={domain}, locales={self.supported_locales}")

get_translations(locale)

指定ロケールの翻訳オブジェクトを返す。

ソースコード位置： pytilpack/i18n.py 
41
42
43
44
45
46
def get_translations(self, locale: str) -> gettext.GNUTranslations | gettext.NullTranslations:
    """指定ロケールの翻訳オブジェクトを返す。"""
    if locale in self.translations:
        return self.translations[locale]
    # 未知のロケールにはNullTranslationsを返す
    return gettext.NullTranslations()

get_state()

現在のI18nStateを返す。未設定時はRuntimeError。

ソースコード位置： pytilpack/i18n.py 
49
50
51
52
53
54
def get_state() -> I18nState:
    """現在のI18nStateを返す。未設定時はRuntimeError。"""
    state = _current_state.get()
    if state is None:
        raise RuntimeError("I18nStateが未設定です。activate()またはフレームワーク統合のinit_app()を呼んでください。")
    return state

get_locale()

現在のロケールを返す。

ソースコード位置： pytilpack/i18n.py 
57
58
59
def get_locale() -> str:
    """現在のロケールを返す。"""
    return _current_locale.get()

set_locale(locale)

現在のコンテキストのロケールを設定する。

ソースコード位置： pytilpack/i18n.py 
62
63
64
def set_locale(locale: str) -> None:
    """現在のコンテキストのロケールを設定する。"""
    _current_locale.set(locale)

activate(state, locale=None)

I18nStateとロケールをコンテキストに設定する。

返されたTokenはdeactivate()に渡してリセットすること。

引数：

名前 タイプ デスクリプション デフォルト
state I18nState

設定するI18nState

 必須
locale str | None

設定するロケール。Noneの場合はstateのdefault_locale

 None

戻り値：

タイプ デスクリプション
tuple[Token[I18nState | None], Token[str]]

(state_token, locale_token) のタプル
ソースコード位置： pytilpack/i18n.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def activate(
    state: I18nState, locale: str | None = None
) -> tuple[contextvars.Token["I18nState | None"], contextvars.Token[str]]:
    """I18nStateとロケールをコンテキストに設定する。

    返されたTokenはdeactivate()に渡してリセットすること。

    Args:
        state: 設定するI18nState
        locale: 設定するロケール。Noneの場合はstateのdefault_locale

    Returns:
        (state_token, locale_token) のタプル

    """
    state_token = _current_state.set(state)
    locale_token = _current_locale.set(locale or state.default_locale)
    return state_token, locale_token

deactivate(tokens)

activate()で取得したTokenを使ってコンテキストをリセットする。

ソースコード位置： pytilpack/i18n.py 
87
88
89
90
91
92
93
def deactivate(
    tokens: tuple[contextvars.Token["I18nState | None"], contextvars.Token[str]],
) -> None:
    """activate()で取得したTokenを使ってコンテキストをリセットする。"""
    state_token, locale_token = tokens
    _current_state.reset(state_token)
    _current_locale.reset(locale_token)

gettext_func(message)

現在のロケールでメッセージを翻訳する。

ソースコード位置： pytilpack/i18n.py 
96
97
98
def gettext_func(message: str) -> str:
    """現在のロケールでメッセージを翻訳する。"""
    return get_state().get_translations(get_locale()).gettext(message)

ngettext(singular, plural, n)

現在のロケールで複数形を考慮してメッセージを翻訳する。

ソースコード位置： pytilpack/i18n.py 
101
102
103
def ngettext(singular: str, plural: str, n: int) -> str:
    """現在のロケールで複数形を考慮してメッセージを翻訳する。"""
    return get_state().get_translations(get_locale()).ngettext(singular, plural, n)

pgettext(context, message)

コンテキスト付きで翻訳する。

ソースコード位置： pytilpack/i18n.py 
106
107
108
def pgettext(context: str, message: str) -> str:
    """コンテキスト付きで翻訳する。"""
    return get_state().get_translations(get_locale()).pgettext(context, message)

npgettext(context, singular, plural, n)

コンテキスト付きで複数形を考慮して翻訳する。

ソースコード位置： pytilpack/i18n.py 
111
112
113
def npgettext(context: str, singular: str, plural: str, n: int) -> str:
    """コンテキスト付きで複数形を考慮して翻訳する。"""
    return get_state().get_translations(get_locale()).npgettext(context, singular, plural, n)