# gt-node: General Translation Node.js SDK: Configurazione
URL: https://generaltranslation.com/it/docs/node/reference/config.mdx
---

title: Configurazione
description: Configura la libreria gt-node di General Translation con initializeGT. Riferimento API per la configurazione di gt-node.

---

La libreria `gt-node` si configura tramite un'unica chiamata a [`initializeGT`](/docs/node/reference/functions/initialize-gt) all'avvio. `gt-node` non legge automaticamente `gt.config.json` né le variabili d'ambiente: ogni valore viene letto dall'oggetto che passi a `initializeGT`. Questa pagina documenta le chiavi accettate da questa chiamata.

## Panoramica [#overview]

Chiama `initializeGT` una sola volta, prima di gestire le richieste, passando un oggetto di configurazione. È sincrona e non restituisce nulla.

```ts
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
  projectId: process.env.GT_PROJECT_ID,
});
```

Le chiavi rispecchiano quelle che la [`gt` CLI](/docs/cli/quickstart) legge da `gt.config.json`. Per mantenere entrambi allineati, importa il tuo `gt.config.json` e usa lo spread dei suoi campi nella chiamata:

```ts
import { initializeGT } from 'gt-node';
import gtConfig from './gt.config.json' with { type: 'json' };

initializeGT(gtConfig);
```

Il tipo di configurazione è `InitializeGTParams`, ossia la combinazione delle opzioni di risoluzione dell'impostazione regionale e delle opzioni della cache di traduzione.

## Opzioni [#options]

| Opzione                                      | Descrizione                                                                                                     | Tipo                                                                  | Facoltativo | Predefinito       |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------- | ----------------- |
| [`defaultLocale`](#default-locale)           | Impostazione regionale sorgente e di fallback.                                                                  | `string`                                                              | Sì          | `'en'`            |
| [`locales`](#locales)                        | Impostazioni regionali di destinazione supportate.                                                              | `string[]`                                                            | Sì          | `[defaultLocale]` |
| [`projectId`](#project-id)                   | ID progetto; quando è impostato, abilita il loader CDN di General Translation.                                  | `string`                                                              | Sì          | —                 |
| [`devApiKey`](#dev-api-key)                  | chiave API di sviluppo per la traduzione su richiesta.                                                          | `string`                                                              | Sì          | —                 |
| [`apiKey`](#api-key)                         | chiave API di produzione.                                                                                       | `string`                                                              | Sì          | —                 |
| [`cacheUrl`](#cache-url)                     | Host della cache delle traduzioni. `null` disabilita il caricamento remoto.                                     | `string \| null`                                                      | Sì          | GT CDN            |
| [`runtimeUrl`](#runtime-url)                 | Host per la traduzione runtime. `null` la disabilita.                                                           | `string \| null`                                                      | Sì          | GT runtime        |
| [`loadTranslations`](#load-translations)     | Loader personalizzato che restituisce le traduzioni per un'impostazione regionale.                          | `TranslationsLoader`                                                  | Sì          | —                 |
| [`customMapping`](#custom-mapping)           | Alias delle impostazioni regionali e override delle proprietà.                                                  | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Sì          | —                 |
| [`cacheExpiryTime`](#cache-expiry)           | Durata della cache per l'impostazione regionale in millisecondi. `null` disabilita la scadenza.             | `number \| null`                                                      | Sì          | —                 |
| [`dictionary`](#dictionary)                  | dizionario nella lingua sorgente letto da [`getTranslations`](/docs/node/reference/functions/get-translations). | `Dictionary`                                                          | Sì          | —                 |
| [`loadDictionary`](#load-dictionary)         | Loader che restituisce un dizionario per un'impostazione regionale.                                         | `DictionaryLoader`                                                    | Sì          | —                 |
| [`runtimeTranslation`](#runtime-translation) | `timeout` e `metadata` della traduzione runtime.                                                                | `object`                                                              | Sì          | `timeout` 12000   |
| [`batchConfig`](#batch-config)               | Limiti di batching della traduzione runtime.                                                                    | `object`                                                              | Sì          | —                 |
| [`modelProvider`](#model-provider)           | Chiave del provider del modello ripresa da `gt.config.json`. Non viene usata dal runtime.                       | `string`                                                              | Sì          | —                 |

*Nota: `initializeGT` accetta anche chiavi interne con prefisso underscore (`_versionId`, `_branchId`, `_disableDevHotReload`) e un oggetto `files` usato dal compilatore CLI. Non fanno parte della superficie pubblica stabile e qui sono omessi.*

## `defaultLocale` [#default-locale]

**Tipo** `string` · **Facoltativo** · **Predefinito** `'en'`

L'impostazione regionale predefinita della tua applicazione. È l'impostazione regionale in cui è scritto il contenuto sorgente e l'impostazione regionale di fallback quando non viene trovata alcuna traduzione. Se omessa, viene usata l'impostazione regionale predefinita della libreria, `'en'`.

```ts
initializeGT({ defaultLocale: 'en-US' });
```

## `locales` [#locales]

**Tipo** `string[]` · **Facoltativo** · **Predefinito** `[defaultLocale]`

Un array di [codici locale](/docs/platform/core/reference/utility-functions/locales/is-valid-locale) supportati dall'applicazione. `defaultLocale` è sempre incluso nell'insieme dei valori supportati, anche se qui viene omesso.

```ts
initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr', 'ja'] });
```

## `projectId` [#project-id]

**Tipo** `string` · **Opzionale**

Il tuo ID progetto di General Translation, richiesto per i servizi cloud di General Translation. Se impostato (senza un `loadTranslations` personalizzato), abilita il loader CDN che carica le traduzioni a runtime.

## `devApiKey` [#dev-api-key]

**Tipo** `string` · **Facoltativo**

Una chiave API di sviluppo. Insieme a un `projectId`, abilita la traduzione runtime on-demand e l'hot reload durante lo sviluppo, così [`getGT`](/docs/node/reference/functions/get-gt), [`getMessages`](/docs/node/reference/functions/get-messages) e [`tx`](/docs/node/reference/functions/tx) possono tradurre nuovi contenuti mentre sviluppi. L'hot reload viene eseguito solo quando `NODE_ENV` non è `'production'`.

## `apiKey` [#api-key]

**Tipo** `string` · **Facoltativo**

Una chiave API di produzione. Impostala quando ti serve la traduzione runtime in produzione. Per la maggior parte delle distribuzioni, invece, le traduzioni vengono generate in anticipo con la [`gt` CLI](/docs/cli/quickstart).

## `cacheUrl` [#cache-url]

**Tipo** `string | null` · **Facoltativo** · **Predefinito** GT CDN

L'URL del servizio di cache delle traduzioni. Impostalo su un host personalizzato per caricare le traduzioni dalla tua CDN oppure su `null` per disattivare il caricamento remoto della cache.

## `runtimeUrl` [#runtime-url]

**Tipo** `string | null` · **Facoltativo** · **Predefinito** GT runtime

L'URL del servizio di traduzione runtime usato da [`tx`](/docs/node/reference/functions/tx) e dalla traduzione di sviluppo on-demand. Impostalo su `null` o `''` per disattivare la traduzione runtime.

## `loadTranslations` [#load-translations]

**Tipo** `TranslationsLoader` · **Facoltativo**

Una funzione personalizzata che carica le traduzioni da una tua sorgente anziché dalla CDN di General Translation. Riceve un codice locale e restituisce le traduzioni per tale impostazione regionale:

```ts
type TranslationsLoader = (locale: string) => Promise<unknown>;
```

```ts
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  loadTranslations: async (locale) => {
    const res = await fetch(`https://my-api.com/translations/${locale}`);
    return res.json();
  },
});
```

## `customMapping` [#custom-mapping]

**Tipo** `CustomMapping` · **Facoltativo**

Una mappatura dei codici locale personalizzati ai codici locale standard o agli override delle [proprietà dell&#39;impostazione regionale](/docs/node/reference/functions/get-locale-properties). Usala per creare un alias per un codice (ad esempio, da `cn` a `zh`) o per sovrascriverne le proprietà di visualizzazione.

## `cacheExpiryTime` [#cache-expiry]

**Tipo** `number | null` · **Facoltativo**

Durata della cache dell&#39;impostazione regionale, in millisecondi. Lascia `undefined` per usare il TTL predefinito, imposta un numero per specificare un TTL esplicito oppure `null` per disabilitare la scadenza.

## `dictionary` [#dictionary]

**Tipo** `Dictionary` · **Facoltativo**

Un dizionario nella lingua sorgente di voci di traduzione indicizzate per id. Le voci vengono risolte a ogni richiesta con [`getTranslations`](/docs/node/reference/functions/get-translations).

## `loadDictionary` [#load-dictionary]

**Tipo** `DictionaryLoader` · **Facoltativo**

Un loader che restituisce un dizionario per una specifica impostazione regionale:

```ts
type DictionaryLoader = (locale: string) => Promise<Dictionary>;
```

## `runtimeTranslation` [#runtime-translation]

**Type** `object` · **Facoltativo** · **Predefinito** `timeout` 12000 ms

Impostazioni di traduzione runtime applicate da [`tx`](/docs/node/reference/functions/tx) e dalla traduzione di sviluppo on-demand:

* `timeout?: number` — timeout della richiesta in millisecondi (predefinito `12000`).
* `metadata?: object` — metadati integrati in ogni richiesta di traduzione runtime. Qui vanno gli hint di traduzione solo runtime, inclusi `modelProvider` (vedi [`modelProvider`](#model-provider) sotto) e `sourceLocale`.

## `batchConfig` [#batch-config]

**Type** `object` · **Facoltativo**

Controlla come [`tx`](/docs/node/reference/functions/tx) e traduzione di sviluppo on-demand raggruppano in batch le richieste di traduzione runtime. Lascia il valore non definito per usare quelli predefiniti.

* `maxConcurrentRequests?: number` — numero massimo di richieste batch simultanee in corso.
* `maxBatchSize?: number` — numero massimo di voci per richiesta batch.
* `batchInterval?: number` — ritardo in millisecondi prima che un batch venga inviato.

## `modelProvider` [#model-provider]

**Tipo** `string` · **Facoltativo**

Corrisponde alla chiave `modelProvider` in `gt.config.json`, che la [`gt` CLI](/docs/cli/quickstart) usa per scegliere un modello di traduzione. Il runtime `gt-node` **non** usa questa chiave di primo livello — viene accettata solo per evitare errori quando si fa lo spread di `gt.config.json`. Per scegliere il modello usato dalla traduzione runtime ([`tx`](/docs/node/reference/functions/tx)), imposta invece `modelProvider` nei `metadata` di [`runtimeTranslation`](#runtime-translation).

## Esempio [#example]

```ts title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});
```