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

title: I18nManager
description: L'orchestratore centrale per le impostazioni regionali, il caricamento delle traduzioni e la cache in General Translation Python. Riferimento API per I18nManager.

---

L'oggetto centrale che gestisce la configurazione delle impostazioni regionali, carica e mette in cache le traduzioni e tiene traccia dell'impostazione regionale della richiesta corrente. [`initialize_gt`](/docs/python/reference/functions/initialize-gt) ne crea uno per te; nella libreria core `gt-i18n` lo costruisci direttamente e lo registri con [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager).

## Panoramica [#overview]

Crea un `I18nManager` con argomenti specificati solo per nome, quindi registralo come gestore attivo. Ogni funzione di traduzione usa il gestore registrato.

```python
from gt_i18n import I18nManager, set_i18n_manager

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

Firma:

```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,
)
```

Importa `I18nManager` da `gt_i18n`. Il framework non lo riesporta nei suoi pacchetti.

## Come funziona [#how-it-works]

* **Insieme di impostazioni regionali.** L'impostazione regionale predefinita viene sempre inclusa in `locales`, quindi l'insieme di impostazioni regionali del gestore la contiene sempre.
* **Selezione del loader.** Se viene fornito `load_translations`, viene usato; altrimenti, se è impostato `project_id`, viene creato un loader CDN per `{cache_url}/{project_id}/{locale}`; altrimenti, un loader no-op restituisce un dict vuoto.
* **Caching.** Le traduzioni caricate vengono memorizzate nella cache per impostazione regionale per `cache_expiry_time` millisecondi. `get_translations` carica su richiesta (async); `get_translations_sync` legge solo dalla cache e non blocca mai.
* **Memorizzazione dell'impostazione regionale.** L'impostazione regionale corrente viene memorizzata tramite `store_adapter` (un [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter) per impostazione predefinita), che isola il valore per ogni richiesta sia nei contesti con thread sia in quelli async.

## Parametri del costruttore [#parameters]

| Parametro                                 | Descrizione                                                                                  | Tipo                                                                       | Facoltativo | Predefinito                |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------- | -------------------------- |
| [`default_locale`](#default-locale)       | Impostazione regionale sorgente e di fallback.                                               | `str`                                                                      | Sì          | `"en"`                     |
| [`locales`](#locales)                     | Impostazioni regionali di destinazione supportate dall'app.                              | `list[str]`                                                                | Sì          | `None`                     |
| [`project_id`](#project-id)               | ID progetto; abilita il loader CDN se impostato.                                             | `str`                                                                      | Sì          | `None`                     |
| [`cache_url`](#cache-url)                 | URL di base del CDN.                                                                         | `str`                                                                      | Sì          | `None`                     |
| [`custom_mapping`](#custom-mapping)       | Codici locale personalizzati e override delle proprietà.                                     | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping)      | Sì          | `None`                     |
| [`store_adapter`](#store-adapter)         | Adattatore di archiviazione personalizzato per l'impostazione regionale della richiesta. | [`StorageAdapter`](/docs/python/reference/classes/storage-adapter)         | Sì          | `ContextVarStorageAdapter` |
| [`load_translations`](#load-translations) | Loader personalizzato; sostituisce il loader CDN.                                            | [`TranslationsLoader`](/docs/python/reference/classes/translations-loader) | Sì          | `None`                     |
| [`cache_expiry_time`](#cache-expiry)      | Durata della cache in millisecondi.                                                          | `int`                                                                      | Sì          | `60000`                    |
| [`version_id`](#version-id)               | Versione della traduzione fissata.                                                           | `str`                                                                      | Sì          | `None`                     |

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

**Tipo** `str` · **Facoltativo** · **Predefinito** `"en"`

L'impostazione regionale sorgente e di fallback. Per impostazione predefinita, corrisponde al valore predefinito della library: `"en"` (`LIBRARY_DEFAULT_LOCALE`).

### `locales` [#locales]

**Tipo** `list[str]` · **Facoltativo** · **Predefinito** `None`

Le impostazioni regionali di destinazione supportate dall'applicazione. L'impostazione regionale predefinita è sempre inclusa.

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

**Type** `str` · **Opzionale** · **Predefinito** `None`

L'ID progetto di General Translation. Quando è impostato e non viene fornito `load_translations`, il manager crea un loader CDN.

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

**Tipo** `str` · **Facoltativo** · **Predefinito** `None`

L'URL di base della CDN utilizzato dal loader remoto. La CDN di General Translation è `https://cdn.gtx.dev`.

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

**Tipo** `CustomMapping` · **Facoltativo** · **Predefinito** `None`

Codici locale personalizzati e override delle proprietà, passati all'istanza [`GT`](/docs/platform/core/reference/gt-class/constructor) sottostante.

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

**Tipo** [`StorageAdapter`](/docs/python/reference/classes/storage-adapter) · **Facoltativo** · **Predefinito** `ContextVarStorageAdapter`

L'adattatore di archiviazione per lo stato dell'impostazione regionale relativo alla singola richiesta. Per impostazione predefinita è [`ContextVarStorageAdapter`](/docs/python/reference/classes/context-var-storage-adapter).

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

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

Un loader personalizzato che restituisce le traduzioni per una determinata impostazione regionale. Se specificato, sostituisce il loader CDN.

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

**Tipo** `int` · **Facoltativo** · **Predefinito** `60000`

Durata della cache in millisecondi (predefinita: 60000, cioè 60 secondi). Quando una entry supera questa soglia di età, viene considerata scaduta: `get_translations` asincrona la ricarica alla chiamata successiva, ma `get_translations_sync` — il metodo usato da [`t`](/docs/python/reference/functions/t) — restituisce un dict vuoto per una entry scaduta e **non** avvia un ricaricamento. Poiché il percorso della richiesta legge le traduzioni in modo sincrono e nulla riesegue il loader asincrono dopo l'avvio, le traduzioni scadute non vengono ricaricate automaticamente e `t` usa come fallback le stringhe sorgente finché `load_all_translations` (o `get_translations`) non viene eseguito di nuovo. `initialize_gt` non espone questo parametro, quindi le app del framework non possono modificare l'intervallo di 60 secondi.

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

**Tipo** `str` · **Facoltativo** · **Predefinito** `None`

Una versione di traduzione fissata, restituita da [`get_version_id`](/docs/python/reference/functions/get-version-id).

## Proprietà e metodi [#members]

| Membro                                         | Descrizione                                                                                      | Restituisce      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------- |
| [`default_locale`](#member-default-locale)     | L'impostazione regionale sorgente/predefinita (proprietà).                                   | `str`            |
| [`get_locale`](#member-get-locale)             | L'impostazione regionale della richiesta corrente, oppure quella predefinita.                | `str`            |
| [`set_locale`](#member-set-locale)             | Imposta l'impostazione regionale della richiesta corrente.                                   | `None`           |
| [`get_locales`](#member-get-locales)           | L'elenco delle impostazioni regionali supportate.                                            | `list[str]`      |
| [`get_version_id`](#member-version-id)         | L'id della versione configurata, oppure `None`.                                              | `str \| None`    |
| [`requires_translation`](#member-requires)     | Indica se un'impostazione regionale richiede la traduzione da quella predefinita.            | `bool`           |
| [`get_translations`](#member-get-translations) | Carica in modo asincrono e memorizza nella cache le traduzioni di un'impostazione regionale. | `dict[str, str]` |
| [`get_translations_sync`](#member-get-sync)    | Legge le traduzioni memorizzate nella cache senza bloccare.                                      | `dict[str, str]` |
| [`load_all_translations`](#member-load-all)    | Carica preventivamente tutte le impostazioni regionali configurate (in modo asincrono).          | `None`           |
| [`get_gt_instance`](#member-gt-instance)       | Crea un'istanza `GT` per la richiesta corrente.                                              | `GT`             |

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

Proprietà di sola lettura che restituisce l'impostazione regionale sorgente o predefinita.

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

Restituisce l'impostazione regionale della richiesta corrente dall'adattatore di archiviazione; se non è disponibile, usa l'impostazione regionale predefinita.

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

Salva l'impostazione regionale della richiesta corrente nell'adattatore di archiviazione.

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

Restituisce una copia dell'elenco delle impostazioni regionali supportate (sempre inclusa l'impostazione regionale predefinita).

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

Restituisce l'identificativo della versione configurata, oppure `None`.

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

Indica se `locale` (o l'impostazione regionale corrente) richiede una traduzione rispetto a quella predefinita, in base ai locales configurati.

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

Un metodo asincrono che carica e memorizza nella cache le traduzioni per `locale` (o l'impostazione regionale corrente), evitando duplicazioni nei caricamenti concorrenti e restituendo un dizionario vuoto in caso di errore.

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

Restituisce le traduzioni memorizzate nella cache per `locale` (o per l'impostazione regionale corrente) senza bloccare l'esecuzione, oppure un dizionario vuoto se nella cache non c'è nulla (o se la cache è scaduta). È ciò che legge [`t`](/docs/python/reference/functions/t).

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

Un metodo asincrono che carica preventivamente le traduzioni per tutte le impostazioni regionali configurate.

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

Restituisce un'istanza `GT` configurata con l'ID progetto del manager, l'impostazione regionale sorgente, l'impostazione regionale di destinazione corrente, `locales` e la mappatura personalizzata.

## Esempio [#example]

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

def load_translations(locale: str) -> dict[str, str]:
    return {}  # carica dalla tua sorgente

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

asyncio.run(manager.load_all_translations())  # precarica
manager.set_locale("es")
t("Hello, world!")
```