# gt-node: General Translation Node.js SDK: Configurazione URL: https://generaltranslation.com/it/docs/node/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt 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. Non legge automaticamente `gt.config.json`, ma usa le variabili d'ambiente come fallback per le credenziali. Questa pagina documenta le chiavi accettate da questa chiamata. ## Panoramica [#overview] Chiama [`initializeGT`](/docs/node/reference/functions/initialize-gt) 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'], }); ``` 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. ## Variabili d'ambiente [#env] I valori espliciti passati a [`initializeGT`](/docs/node/reference/functions/initialize-gt) hanno la precedenza sulle variabili d'ambiente. | Variabile | Descrizione | | ---------------- | ------------------------------------------------------------- | | `GT_PROJECT_ID` | ID progetto usato quando `projectId` viene omesso. | | `GT_DEV_API_KEY` | Chiave API di sviluppo usata quando `devApiKey` viene omesso. | | `GT_API_KEY` | Chiave API di produzione usata quando `apiKey` viene omesso. | ## 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ì | `GT_PROJECT_ID` se impostato | | [`devApiKey`](#dev-api-key) | chiave API di sviluppo per la traduzione su richiesta. | `string` | Sì | `GT_DEV_API_KEY` se impostato | | [`apiKey`](#api-key) | chiave API di produzione. | `string` | Sì | `GT_API_KEY` se impostato | | [`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 dell'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`](/docs/node/reference/functions/initialize-gt) 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.* ## Credenziali dall'ambiente [#environment] Quando una credenziale viene omessa dall'oggetto di configurazione, [`initializeGT`](/docs/node/reference/functions/initialize-gt) legge la variabile d'ambiente corrispondente: | Opzione | Variabile d'ambiente | Precedenza | | ----------- | ------------------------ | --------------------------------------------------------- | | `projectId` | `GT_PROJECT_ID` | Opzione esplicita non vuota, poi variabile d'ambiente | | `devApiKey` | `GT_DEV_API_KEY` | Opzione esplicita non vuota, poi variabile d'ambiente | | `apiKey` | `GT_API_KEY` | Opzione esplicita non vuota, poi variabile d'ambiente | Una stringa esplicita vuota viene trattata come assente e usa quindi il valore dell'ambiente come fallback. Gli altri campi di configurazione, inclusi `locales` e i loader delle traduzioni, non vengono letti dall'ambiente. ## `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` · **facoltativo** · **Predefinito** `GT_PROJECT_ID` se impostato Il tuo ID progetto di General Translation, richiesto per i servizi cloud di General Translation. Se omesso, usa `GT_PROJECT_ID` come fallback. Se impostato (senza un `loadTranslations` personalizzato), abilita il loader CDN che carica le traduzioni a runtime. ## `devApiKey` [#dev-api-key] **Tipo** `string` · **Facoltativo** · **Predefinito** `GT_DEV_API_KEY` se impostato Una chiave API di sviluppo. Se omessa, utilizza `GT_DEV_API_KEY` come fallback. 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 in un ambiente di sviluppo, ovvero quando `NODE_ENV` è esattamente `'development'`, oppure `import.meta.env.MODE` è `'development'`, oppure `import.meta.env.DEV` è `true`. Qualsiasi altro valore è considerato produzione, incluso un `NODE_ENV` non impostato, quindi imposta `NODE_ENV=development` per l'hot reload. ## `apiKey` [#api-key] **Tipo** `string` · **Facoltativo** · **Predefinito** `GT_API_KEY` se impostata Una chiave API di produzione. Se omessa, usa `GT_API_KEY` come fallback. 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; ``` ```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`](/docs/platform/core/reference/types/custom-mapping) · **Facoltativo** Una mappatura dei codici locale personalizzati ai codici locale standard o agli override delle [proprietà dell'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'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; ``` ## `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'], // Le credenziali vengono lette da GT_PROJECT_ID, GT_API_KEY e GT_DEV_API_KEY. }); ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.