# General Translation Python SDKs: I18nManager
URL: https://generaltranslation.com/ru/docs/python/reference/classes/i18n-manager.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Центральный координатор локалей, загрузки переводов и кэширования в General Translation Python. Справочник по API для I18nManager.

Центральный объект, который хранит конфигурацию локалей, загружает и кэширует переводы, а также отслеживает локаль текущего запроса. [`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,
)
```

Импортируйте `I18nManager` из `gt_i18n`. Пакеты фреймворка его не реэкспортируют.

## Как это работает [#how-it-works]

* **Набор локалей.** Локаль по умолчанию всегда добавляется в `locales`, поэтому набор локалей менеджера всегда её содержит.
* **Выбор загрузчика.** Если передан `load_translations`, используется он; иначе, если задан `project_id`, создаётся CDN-загрузчик для `{cache_url}/{project_id}/{locale}`; в противном случае загрузчик-заглушка возвращает пустой `dict`.
* **Кэширование.** Загруженные переводы кэшируются отдельно для каждой локали на `cache_expiry_time` миллисекунд. `get_translations` загружает их по запросу (async); `get_translations_sync` только читает кэш и никогда не блокирует выполнение.
* **Хранение локали.** Текущая локаль хранится через `store_adapter` (по умолчанию — [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter)), который изолирует значение для каждого запроса как в потоковых, так и в async-контекстах.

## Параметры конструктора [#parameters]

| Параметр                                  | Описание                                                    | Тип                                                                        | Необязательно | По умолчанию                                                                             |
| ----------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- |
| [`default_locale`](#default-locale)       | Исходная и резервная локаль.                                | `str`                                                                      | Да            | `"en"`                                                                                   |
| [`locales`](#locales)                     | Целевые локали, поддерживаемые приложением.                 | `list[str]`                                                                | Да            | `None`                                                                                   |
| [`project_id`](#project-id)               | ID проекта; при указании включает CDN-загрузчик.            | `str`                                                                      | Да            | `None`                                                                                   |
| [`cache_url`](#cache-url)                 | Базовый URL CDN.                                            | `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`](/docs/python/reference/classes/context-var-storage-adapter) |
| [`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`

ID проекта General Translation. Если он задан и `load_translations` не указан, менеджер создает CDN-загрузчик.

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

**Тип** `str` · **Необязательный** · **По умолчанию** `None`

Базовый URL CDN, используемый удалённым загрузчиком. CDN General Translation — `https://cdn.gtx.dev`.

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

**Тип** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Необязательно** · **По умолчанию** `None`

Пользовательские коды локалей и переопределения свойств, передаваемые внутреннему экземпляру [`GT`](/docs/platform/core/reference/gt-class/constructor).

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

**Тип** [`StorageAdapter`](/docs/python/reference/classes/storage-adapter) · **Необязательно** · **По умолчанию** [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter)

Адаптер хранилища для состояния локали в рамках запроса. По умолчанию используется [`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`](/docs/python/reference/functions/t) возвращает исходные строки, пока снова не будет вызван `load_all_translations` (или `get_translations`). [`initialize_gt`](/docs/python/reference/functions/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` (или текущей локали), предотвращает дублирование при одновременных загрузках и в случае ошибки возвращает пустой словарь.

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

Возвращает кэшированные переводы для `locale` (или текущей локали) без блокировки либо пустой словарь, если в кэше ничего нет (или срок его действия истёк). Эти данные считывает [`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!")
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.