# General Translation Python SDKs: I18nManager
URL: https://generaltranslation.com/ja/docs/python/reference/classes/i18n-manager.mdx
---

title: I18nManager
description: General Translation Python でロケール、翻訳の読み込み、キャッシュを一元管理する中心オブジェクト。I18nManager の API リファレンス。

---

ロケール設定を保持し、翻訳を読み込んでキャッシュし、現在のリクエストのロケールを追跡する中心的なオブジェクトです。[`initialize_gt`](/docs/python/reference/functions/initialize-gt) はこれを自動的に構築します。コア `gt-i18n` ライブラリでは、これを直接構築し、[`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager) で登録します。

## 概要 [#overview]

keyword-only 引数で `I18nManager` を構築し、アクティブなマネージャーとして登録します。すべての翻訳関数は、登録されたマネージャーを参照します。

```python
from gt_i18n import I18nManager, set_i18n_manager

manager = I18nManager(default_locale="en", locales=["es", "fr"])
set_i18n_manager(manager)
```

シグネチャ:

```python
I18nManager(
    *,
    default_locale: str = "en",
    locales: list[str] | None = None,
    project_id: str | None = None,
    cache_url: str | None = None,
    custom_mapping: CustomMapping | None = None,
    store_adapter: StorageAdapter | None = None,
    load_translations: TranslationsLoader | None = None,
    cache_expiry_time: int = 60_000,
    version_id: str | None = None,
)
```

`gt_i18n` から `I18nManager` をインポートしてください。フレームワークのパッケージからは再エクスポートされていません。

## 仕組み [#how-it-works]

* **ロケールセット。** デフォルトロケールは常に `locales` にマージされるため、manager のロケールセットには必ず含まれます。
* **ローダーの選択。** `load_translations` が指定されている場合はそれを使用します。指定されていない場合は、`project_id` が設定されていれば `{cache_url}/{project_id}/{locale}` 用の CDN ローダーが作成され、どちらでもなければ空の dict を返す no-op ローダーが使われます。
* **キャッシュ。** 読み込まれた翻訳は、ロケールごとに `cache_expiry_time` ミリ秒間キャッシュされます。`get_translations` は必要に応じて読み込みます (非同期) 。`get_translations_sync` はキャッシュを参照するだけで、待機は一切発生しません。
* **ロケールの保存。** 現在のロケールは `store_adapter` を通じて保存されます (デフォルトは [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter)) 。これにより、スレッド環境と非同期コンテキストの両方で、値がリクエストごとに分離されます。

## コンストラクタのパラメータ [#parameters]

| パラメータ                                     | 説明                               | 型                                                                          | 任意 | デフォルト                      |
| ----------------------------------------- | -------------------------------- | -------------------------------------------------------------------------- | -- | -------------------------- |
| [`default_locale`](#default-locale)       | ソースロケールおよびフォールバックロケール。           | `str`                                                                      | はい | `"en"`                     |
| [`locales`](#locales)                     | アプリがサポートするターゲットロケール。             | `list[str]`                                                                | はい | `None`                     |
| [`project_id`](#project-id)               | プロジェクトID。設定すると CDN ローダーが有効になります。 | `str`                                                                      | はい | `None`                     |
| [`cache_url`](#cache-url)                 | CDN のベース URL。                    | `str`                                                                      | はい | `None`                     |
| [`custom_mapping`](#custom-mapping)       | カスタムのロケールコードとプロパティの上書き。          | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping)      | はい | `None`                     |
| [`store_adapter`](#store-adapter)         | リクエストロケール用のカスタムストレージアダプター。       | [`StorageAdapter`](/docs/python/reference/classes/storage-adapter)         | はい | `ContextVarStorageAdapter` |
| [`load_translations`](#load-translations) | カスタムローダー。CDN ローダーを上書きします。        | [`TranslationsLoader`](/docs/python/reference/classes/translations-loader) | はい | `None`                     |
| [`cache_expiry_time`](#cache-expiry)      | キャッシュの有効期間 (ミリ秒) 。               | `int`                                                                      | はい | `60000`                    |
| [`version_id`](#version-id)               | 固定する翻訳バージョン。                     | `str`                                                                      | はい | `None`                     |

### `default_locale` [#default-locale]

**型** `str` · **任意** · **デフォルト** `"en"`

ソースロケールおよびフォールバックロケールです。デフォルトでは、ライブラリのデフォルト値 `"en"` (`LIBRARY_DEFAULT_LOCALE`) が使用されます。

### `locales` [#locales]

**型** `list[str]` · **省略可** · **デフォルト** `None`

アプリケーションがサポートするターゲットロケール。デフォルトロケールは常にこのセットに追加されます。

### `project_id` [#project-id]

**型** `str` · **任意** · **デフォルト** `None`

General Translation のプロジェクト ID です。これが設定されており、`load_translations` が指定されていない場合、マネージャーは CDN ローダーを作成します。

### `cache_url` [#cache-url]

**型** `str` · **省略可** · **デフォルト** `None`

リモート `ローダー` で使用する CDN のベース URL です。General Translation の CDN は `https://cdn.gtx.dev` です。

### `custom_mapping` [#custom-mapping]

**Type** `CustomMapping` · **Optional** · **Default** `None`

カスタムのロケールコードとプロパティのオーバーライド。これらは基盤となる[`GT`](/docs/platform/core/reference/gt-class/constructor)インスタンスに渡されます。

### `store_adapter` [#store-adapter]

**Type** [`StorageAdapter`](/docs/python/reference/classes/storage-adapter) · **Optional** · **デフォルト** `ContextVarStorageAdapter`

リクエストごとのロケール状態を保持するストレージアダプターです。デフォルトは [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter) です。

### `load_translations` [#load-translations]

**Type** [`TranslationsLoader`](/docs/python/reference/classes/translations-loader) · **Optional** · **Default** `None`

指定したロケールの翻訳を返すカスタムローダーです。指定すると、CDNローダーより優先されます。

### `cache_expiry_time` [#cache-expiry]

**Type** `int` · **Optional** · **Default** `60000`

キャッシュの有効期間をミリ秒単位で指定します (既定値は 60000、つまり 60 秒) 。エントリがこの時間を超えると、期限切れとして扱われます。非同期の `get_translations` は次回呼び出し時にそのエントリを再読み込みしますが、[`t`](/docs/python/reference/functions/t) メソッドが使用する `get_translations_sync` は、期限切れのエントリに対して空の dict を返すだけで、再読み込みは**トリガーしません**。リクエストパスでは翻訳を同期的に読み込み、起動後に非同期 ローダー を再実行する仕組みもないため、期限切れになった翻訳は自動的には再読み込みされず、`load_all_translations` (または `get_translations`) が再度実行されるまで、`t` は source string にフォールバックします。`initialize_gt` ではこのパラメータを公開していないため、フレームワークアプリではこの 60 秒の有効期間を変更できません。

### `version_id` [#version-id]

**型** `str` · **省略可** · **デフォルト** `None`

固定された翻訳バージョンの ID。[`get_version_id`](/docs/python/reference/functions/get-version-id) が返します。

## プロパティとメソッド [#members]

| メンバー                                           | 説明                                | 戻り値              |
| ---------------------------------------------- | --------------------------------- | ---------------- |
| [`default_locale`](#member-default-locale)     | ソース/デフォルトロケール (プロパティ) 。           | `str`            |
| [`get_locale`](#member-get-locale)             | 現在のリクエストのロケール。未設定の場合はデフォルトロケール。   | `str`            |
| [`set_locale`](#member-set-locale)             | 現在のリクエストのロケールを設定します。              | `None`           |
| [`get_locales`](#member-get-locales)           | サポートされているロケールの一覧。                 | `list[str]`      |
| [`get_version_id`](#member-version-id)         | 設定されている バージョンID、または `None`。    | `str \| None`    |
| [`requires_translation`](#member-requires)     | あるロケールでデフォルトロケールからの翻訳が必要かどうか。     | `bool`           |
| [`get_translations`](#member-get-translations) | ロケールの翻訳を読み込み (非同期) 、キャッシュします。     | `dict[str, str]` |
| [`get_translations_sync`](#member-get-sync)    | ブロックせずに、キャッシュ済みの翻訳を読み取ります。        | `dict[str, str]` |
| [`load_all_translations`](#member-load-all)    | 設定されているすべてのロケールを事前に読み込みます (非同期) 。 | `None`           |
| [`get_gt_instance`](#member-gt-instance)       | 現在のリクエスト用に `GT` インスタンスを構築します。     | `GT`             |

### `default_locale` [#member-default-locale]

source/デフォルトロケールを返す読み取り専用のプロパティです。

### `get_locale()` [#member-get-locale]

ストレージアダプターから現在のリクエストのロケールを返し、取得できない場合はデフォルトロケールを使用します。

### `set_locale(locale)` [#member-set-locale]

現在のリクエストのロケールをストレージアダプターに保存します。

### `get_locales()` [#member-get-locales]

サポートされているロケール一覧のコピーを返します (デフォルトロケールは常に含まれます) 。

### `get_version_id()` [#member-version-id]

設定されているバージョンID、または `None` を返します。

### `requires_translation(locale=None)` [#member-requires]

`locale` (または現在のロケール) について、設定されているロケールに基づき、デフォルトからの翻訳が必要かどうかを返します。

### `get_translations(locale=None)` [#member-get-translations]

`locale` (または現在のロケール) の翻訳を読み込んでキャッシュする非同期メソッドです。並行した読み込みは重複を排除し、エラー時には空のdictを返します。

### `get_translations_sync(locale=None)` [#member-get-sync]

`locale` (または現在のロケール) に対応するキャッシュ済みの翻訳を、ブロックせずに返します。キャッシュが存在しない場合 (または有効期限切れの場合) は、空の dict を返します。[`t`](/docs/python/reference/functions/t) はこれを参照します。

### `load_all_translations()` [#member-load-all]

設定されているすべてのロケールの翻訳をあらかじめ読み込む非同期メソッドです。

### `get_gt_instance()` [#member-gt-instance]

manager のプロジェクト ID、ソースロケール、現在の対象ロケール、locales、カスタムマッピングを使って設定された `GT` インスタンスを返します。

## 例 [#example]

```python
import asyncio
from gt_i18n import I18nManager, set_i18n_manager, t

def load_translations(locale: str) -> dict[str, str]:
    return {}  # 独自のソースから読み込む

manager = I18nManager(default_locale="en", locales=["es"], load_translations=load_translations)
set_i18n_manager(manager)

asyncio.run(manager.load_all_translations())  # 事前読み込み
manager.set_locale("es")
t("Hello, world!")
```