# General Translation Python SDKs: initialize_gt
URL: https://generaltranslation.com/it/docs/python/reference/functions/initialize-gt.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Configura una sola volta l'SDK Python di General Translation per un'app Flask o FastAPI. Riferimento API per initialize_gt.

Configura General Translation per un'app Flask o FastAPI. Chiama `initialize_gt` una sola volta all'avvio, prima di qualsiasi altra funzione di traduzione, per creare il manager delle traduzioni, registrare il rilevamento dell'impostazione regionale per richiesta e configurare la distribuzione delle traduzioni.

## Panoramica [#overview]

Chiama `initialize_gt` passando la tua app. Le impostazioni vengono caricate da `gt.config.json` nella directory di lavoro corrente e gli eventuali argomenti con nome sovrascrivono i valori del file. Restituisce l'[`I18nManager`](/docs/python/reference/classes/i18n-manager) configurato e lo registra come manager attivo, così le chiamate successive a [`t`](/docs/python/reference/functions/t) e le funzioni di supporto per l'impostazione regionale funzionano automaticamente.

```python
from flask import Flask
from gt_flask import initialize_gt

app = Flask(__name__)
initialize_gt(app)
```

Firma:

```python
initialize_gt(
    app,
    *,
    default_locale: str | None = None,
    locales: list[str] | None = None,
    custom_mapping: CustomMapping | None = None,
    project_id: str | None = None,
    cache_url: str | None = None,
    version_id: str | None = None,
    get_locale: Callable[..., str] | None = None,
    load_translations: Callable[[str], dict[str, str]] | None = None,
    eager_loading: bool = True,
    config_path: str | None = None,
    load_config: Callable[[str | None], GTConfig] | None = None,
) -> I18nManager
```

Importa `initialize_gt` da `gt_flask` o `gt_fastapi`, a seconda del framework che usi. La firma è identica in entrambi i casi. Non esiste un `initialize_gt` nella libreria core; se non usi un framework, crea un [`I18nManager`](/docs/python/reference/classes/i18n-manager) e chiama invece [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager).

*Nota: non esiste alcun parametro `api_key`. La distribuzione tramite CDN è gestita da `project_id` e `cache_url`.*

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

* **Risoluzione della configurazione.** Carica la configurazione (tramite `load_config`, un `config_path` esplicito o il valore predefinito `gt.config.json`), quindi determina ogni impostazione nel seguente ordine: argomento keyword, valore di configurazione, valore predefinito della library.
* **Inizializzazione del manager.** Crea un [`I18nManager`](/docs/python/reference/classes/i18n-manager) con le impostazioni determinate e lo registra con [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager).
* **Rilevamento dell'impostazione regionale.** In Flask registra un hook `before_request`; in FastAPI aggiunge un middleware HTTP e avvolge il ciclo di vita dell'app. Ogni richiesta imposta l'impostazione regionale da [`get_locale`](/docs/python/reference/functions/get-locale), se fornito; altrimenti, dall'header `Accept-Language`.
* **Caricamento anticipato.** Quando `eager_loading` è true e i locales di destinazione sono noti, carica tutte le traduzioni in anticipo. In Flask controlla l'argomento `locales` passato direttamente (non le locales presenti solo nella configurazione); in FastAPI viene eseguito all'interno del ciclo di vita avvolto sui locales determinati.

## Parametri [#parameters]

| Parametro                                 | Descrizione                                                                            | Tipo                                                                  | Facoltativo | Predefinito        |
| ----------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------- | ------------------ |
| [`app`](#app)                             | L'istanza dell'applicazione Flask o FastAPI.                                   | `Flask \| FastAPI`                                                    | No          | —                  |
| [`default_locale`](#default-locale)       | Impostazione regionale sorgente e di fallback.                                         | `str`                                                                 | Sì          | Config, poi `"en"` |
| [`locales`](#locales)                     | Locales di destinazione supportati.                                                    | `list[str]`                                                           | Sì          | Config             |
| [`custom_mapping`](#custom-mapping)       | Codici locale personalizzati e override delle proprietà.                               | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Sì          | Config             |
| [`project_id`](#project-id)               | ID progetto; abilita il loader CDN quando è impostato.                                 | `str`                                                                 | Sì          | Config             |
| [`cache_url`](#cache-url)                 | Override dell'URL di base della CDN.                                               | `str`                                                                 | Sì          | Config             |
| [`version_id`](#version-id)               | Versione di traduzione fissata.                                                        | `str`                                                                 | Sì          | Config             |
| [`get_locale`](#get-locale)               | Callback personalizzata per il rilevamento dell'impostazione regionale.            | `(request) -> str`                                                    | Sì          | `Accept-Language`  |
| [`load_translations`](#load-translations) | Loader personalizzato che restituisce le traduzioni per un'impostazione regionale. | `(locale: str) -> dict[str, str]`                                     | Sì          | —                  |
| [`eager_loading`](#eager-loading)         | Precarica tutte le traduzioni all'avvio.                                           | `bool`                                                                | Sì          | `True`             |
| [`config_path`](#config-path)             | Percorso di un file `gt.config.json`.                                                  | `str`                                                                 | Sì          | `gt.config.json`   |
| [`load_config`](#load-config)             | Loader di configurazione personalizzato che sostituisce quello predefinito.            | `(path: str \| None) -> GTConfig`                                     | Sì          | —                  |

### `app` [#app]

**Tipo** `Flask | FastAPI` · **Obbligatorio**

L'istanza dell'applicazione da configurare. Viene passata come argomento posizionale; tutti gli altri parametri sono solo keyword.

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

**Tipo** `str` · **Facoltativo** · **Predefinito** valore di configurazione, poi `"en"`

L'impostazione regionale sorgente in cui sono scritti i tuoi contenuti e il fallback se non viene trovata alcuna traduzione. Viene risolto prima con l'argomento, poi con `defaultLocale` in `gt.config.json`, quindi con `"en"`.

### `locales` [#locales]

**Tipo** `list[str]` · **Facoltativo** · **Valore predefinito della configurazione**

Le locales di destinazione da supportare. Corrisponde all'argomento; in caso contrario, all'array `locales` in `gt.config.json`. L'impostazione regionale predefinita è sempre inclusa nel set di locales del manager.

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

**Tipo** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Facoltativo** · Valore di configurazione **predefinito**

Una mappatura di codici locale personalizzati a codici standard o a override delle proprietà. Vedi [`customMapping`](/docs/python/reference/config#custom-mapping).

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

**Tipo** `str` · **Facoltativo** · **Valore di configurazione predefinito**

L'ID progetto di General Translation. Se impostato (e se non viene fornito `load_translations`), abilita il caricamento delle traduzioni dal CDN all'indirizzo `{cache_url}/{project_id}/{locale}`.

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

**Type** `str` · **Facoltativo** · **Valore di configurazione predefinito**

Una sostituzione dell'URL di base della CDN usato per caricare le traduzioni. La CDN di General Translation è `https://cdn.gtx.dev`.

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

**Tipo** `str` · **Facoltativo** · **Valore di configurazione predefinito**

Una versione di traduzione fissata da caricare. Corrisponde alla chiave di configurazione `_versionId` ed è restituita da [`get_version_id`](/docs/python/reference/functions/get-version-id).

### `get_locale` [#get-locale]

**Tipo** `(request) -> str` · **Facoltativo** · **Predefinito** parsing di `Accept-Language`

Un callback personalizzato per il rilevamento dell'impostazione regionale. Riceve la richiesta e restituisce un codice locale, sostituendo completamente il rilevamento integrato di `Accept-Language`. Un valore di ritorno falsy corrisponde all'impostazione regionale predefinita.

```python
def get_locale(request):
    return request.args.get("lang") or "en"

initialize_gt(app, get_locale=get_locale)
```

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

**Tipo** `(locale: str) -> dict[str, str]` · **Facoltativo**

Una funzione personalizzata che carica le traduzioni per un'impostazione regionale dalla tua sorgente anziché dalla CDN. Se specificata, sostituisce il loader della CDN. Può essere sincrona oppure restituire un awaitable.

```python
def load_translations(locale: str) -> dict[str, str]:
    # Carica le traduzioni dalla tua sorgente
    ...

initialize_gt(app, load_translations=load_translations)
```

### `eager_loading` [#eager-loading]

**Tipo** `bool` · **Facoltativo** · **Predefinito** `True`

Se è impostato su true, tutte le traduzioni vengono caricate all'avvio invece che al primo utilizzo. Consulta la nota [Come funziona](#how-it-works) sulla differenza tra impostazione regionale e sorgente tra Flask e FastAPI.

### `config_path` [#config-path]

**Type** `str` · **Facoltativo** · **Predefinito** `gt.config.json`

Il percorso di un file `gt.config.json`. Per impostazione predefinita, corrisponde a `gt.config.json` nella directory di lavoro corrente. Se viene specificato un percorso esplicito che non esiste, viene generato `FileNotFoundError`.

### `load_config` [#load-config]

**Tipo** `(path: str | None) -> GTConfig` · **Facoltativo**

Un loader di configurazione personalizzato che sostituisce quello predefinito per i file. Riceve `config_path` e restituisce un dizionario `GTConfig`.

## Restituisce [#returns]

**Tipo** [`I18nManager`](/docs/python/reference/classes/i18n-manager)

L'[`I18nManager`](/docs/python/reference/classes/i18n-manager) configurato, già registrato come manager attivo.

## Esempi [#examples]

```python
# Setup minimale, lettura di gt.config.json
from flask import Flask
from gt_flask import initialize_gt

app = Flask(__name__)
initialize_gt(app)
```

```python
# Locales espliciti con un loader delle traduzioni personalizzato
from fastapi import FastAPI
from gt_fastapi import initialize_gt

app = FastAPI()

def load_translations(locale: str) -> dict[str, str]:
    # Carica le traduzioni dalla tua sorgente
    ...

initialize_gt(app, default_locale="en", locales=["es", "fr"], load_translations=load_translations)
```

## Sitemap

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