# General Translation Python SDKs: I18nManager
URL: https://generaltranslation.com/zh/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]

使用仅限关键字参数来构造 `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` 中，因此管理器的区域设置集合始终会包含它。
* **加载器选择。** 如果提供了 `load_translations`，则使用它；否则，如果设置了 `project_id`，则会为 `{cache_url}/{project_id}/{locale}` 创建一个 CDN 加载器；再否则，则使用一个不执行任何操作并返回空 dict 的加载器。
* **缓存。** 已加载的翻译会按区域设置缓存 `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]

**Type** `str` · **可选** · **默认值** `None`

远程加载器使用的 CDN 基础 URL。General Translation 的 CDN 为 `https://cdn.gtx.dev`。

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

**类型** `CustomMapping` · **可选** · **默认值** `None`

自定义区域设置代码和属性覆写，并会传递给底层的 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例。

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

**类型** [`StorageAdapter`](/docs/python/reference/classes/storage-adapter) · **可选** · **默认值** `ContextVarStorageAdapter`

用于存储请求级区域设置状态的适配器。默认为 [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter)。

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

**类型** [`TranslationsLoader`](/docs/python/reference/classes/translations-loader) · **可选** · **默认值** `None`

用于返回某个区域设置翻译内容的自定义加载器。提供后将覆盖 CDN 加载器。

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

**类型** `int` · **可选** · **默认值** `60000`

缓存有效期，以毫秒为单位 (默认值为 60000，即 60 秒) 。一旦某个条目超过这个时长，就会被视为已过期：异步 `get_translations` 会在下一次调用时重新加载它，但 `get_translations_sync`——即 [`t`](/docs/python/reference/functions/t) 使用的方法——对于已过期的条目会返回空 `dict`，并且**不会**触发重新加载。由于请求路径会同步读取翻译，而应用启动后也不会再次运行异步加载器，因此过期的翻译不会自动重新加载，`t` 会回退到源 strings，直到 `load_all_translations` (或 `get_translations`) 再次运行。`initialize_gt` 不提供这个参数，因此框架应用无法修改这个 60 秒的时间窗口。

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

**类型** `str` · **可选** · **默认值** `None`

已固定的翻译版本，由 [`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]

一个只读属性，返回源/默认区域设置。

### `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` (或当前区域设置) 相对于默认值是否需要翻译，并根据已配置的 locales 进行判断。

### `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]

返回一个 `GT` 实例，其配置包含管理器的项目 ID、源区域设置、当前目标区域设置、locales 以及自定义映射。

## 示例 [#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!")
```