# General Translation React SDKs (gt-react, gt-next): Configurazione URL: https://generaltranslation.com/it/docs/react/nextjs/config.mdx --- title: Configurazione description: Configura General Translation in un'app Next.js con il plugin `withGTConfig` di `gt-next/config`, le sue opzioni e le traduzioni locali rispetto a quelle distribuite tramite CDN. Riferimento API per `withGTConfig`. --- `withGTConfig` è il plugin di configurazione di `gt-next`. Avvolgi con esso la configurazione di Next.js in `next.config` per abilitare l'internazionalizzazione in fase di build. Legge il file `gt.config.json`, lo combina con le opzioni che passi e con le variabili d'ambiente, quindi configura il compilatore, il caricamento delle traduzioni e la gestione delle richieste. Questa pagina documenta il plugin e le sue opzioni. Per le impostazioni condivise relative alle impostazioni regionali e ai file in `gt.config.json`, consulta il [riferimento della configurazione di `gt-react`](/docs/react/reference/config); per lo schema `files` lato CLI, consulta il [riferimento della configurazione della CLI](/docs/cli/reference/config). ## Panoramica [#overview] Importa `withGTConfig` da `gt-next/config` e usalo per racchiudere la configurazione di Next.js. Puoi passare le opzioni come secondo argomento, ma nella maggior parte dei progetti le impostazioni regionali vengono invece definite in `gt.config.json`. ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; import type { NextConfig } from 'next'; const nextConfig: NextConfig = { // la tua configurazione Next.js esistente }; export default withGTConfig(nextConfig, { defaultLocale: 'en', locales: ['es', 'fr', 'ja'], }); ``` `withGTConfig` deve essere usato in `next.config` — è l'unico punto in cui l'internazionalizzazione viene integrata nel processo di build. ## Come funziona [#how-it-works] * **Risoluzione della configurazione.** Per impostazione predefinita, il plugin carica `./gt.config.json` (verifica anche `./.gt/gt.config.json` e `./.locadex/gt.config.json`). I valori vengono combinati con questa precedenza: **opzioni specificate > variabili d'ambiente > `gt.config.json` > valori predefiniti.** Se una chiave impostata sia in `gt.config.json` sia nelle opzioni ha valori diversi, la build genera un errore di conflitto, quindi mantieni ogni valore in un unico posto. * **Le credenziali provengono dall'ambiente.** Non puoi passare `projectId`, `apiKey` o `devApiKey` come opzioni: impostali come variabili d'ambiente (vedi [Credentials](#credentials)). * **Standardizzazione dei codici locale.** Quando i servizi di General Translation sono abilitati, i codici locale vengono standardizzati nel formato canonico BCP 47 e le impostazioni regionali non valide generano un errore in fase di build. * **Distribuzione delle traduzioni.** Se viene risolto un file [`loadTranslations`](/docs/react/reference/functions/load-translations), le traduzioni vengono caricate dal bundle; altrimenti vengono recuperate dalla CDN di General Translation. Vedi [Traduzioni locali vs. CDN](#translations). ## Credenziali [#credentials] Imposta il tuo ID progetto e le chiavi API come variabili d'ambiente, mai come opzioni del plugin: | Variabile | Descrizione | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `GT_PROJECT_ID` (or `NEXT_PUBLIC_GT_PROJECT_ID`) | Il tuo ID progetto di General Translation. | | `GT_API_KEY` | Chiave API di produzione (con prefisso `gtx-api-`), usata dalla CLI e dalle build di produzione. | | `GT_DEV_API_KEY` (or `NEXT_PUBLIC_GT_DEV_API_KEY`) | Chiave API di sviluppo (con prefisso `gtx-dev-`), per la traduzione su richiesta in sviluppo. | *Avvertenza: non anteporre mai il prefisso `NEXT_PUBLIC_` a una chiave API di produzione e non includere una chiave di sviluppo in produzione: la build genera un errore se `GT_DEV_API_KEY` è presente con `NODE_ENV=production`.* ## Opzioni [#options] Tutte le opzioni sono facoltative. Le opzioni relative all'impostazione regionale sono in genere definite in `gt.config.json` anziché qui. ### Opzioni delle impostazioni regionali [#locale-options] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- | ----------- | ----------- | | [`defaultLocale`](#default-locale) | Impostazione regionale sorgente in cui è scritta la tua app. | `string` | Sì | `en` | | [`locales`](#locales) | Impostazioni regionali di destinazione in cui tradurre la tua app. | `string[]` | Sì | `[]` | | [`ignoreBrowserLocales`](#ignore-browser-locales) | Ignora le impostazioni regionali preferite del browser durante il rilevamento. | `boolean` | Sì | `false` | | [`disableInvalidLocaleWarning`](#disable-invalid-locale-warning) | Sopprime gli avvisi relativi alle impostazioni regionali della richiesta non valide. | `boolean` | Sì | `false` | | [`description`](#description) | Descrizione in linguaggio naturale della tua app, usata per orientare la traduzione. | `string` | Sì | — | ### Distribuzione delle traduzioni [#delivery-options] | Opzione | Descrizione | Type | Facoltativo | Predefinito | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------- | ----------- | ----------------------- | | [`runtimeUrl`](#runtime-url) | URL di base per l'API di General Translation. Una stringa vuota disabilita la traduzione runtime. | `string \| null` | Sì | GT runtime | | [`cacheUrl`](#cache-url) | URL delle traduzioni memorizzate nella cache. | `string \| null` | Sì | GT CDN | | [`cacheExpiryTime`](#cache-expiry-time) | Millisecondi prima della scadenza delle traduzioni memorizzate localmente nella cache. | `number` | Sì | `60000` | | [`loadTranslationsPath`](#load-translations-path) | Percorso di un file `loadTranslations` personalizzato. | `string` | Sì | Risolto automaticamente | | [`loadDictionaryPath`](#load-dictionary-path) | Percorso di un file [`loadDictionary`](/docs/react/reference/functions/load-dictionary) personalizzato. | `string` | Sì | Risolto automaticamente | | [`dictionary`](#dictionary) | Percorso del file del dizionario. | `string` | Sì | Risolto automaticamente | | [`config`](#config-path) | Percorso del file `gt.config.json`. | `string` | Sì | `./gt.config.json` | ### Rendering [#rendering-options] | Opzione | Descrizione | Type | Facoltativo | Predefinito | | ------------------------------------ | ----------------------------------------------------------------------- | -------- | ----------- | ----------- | | [`renderSettings`](#render-settings) | Come vengono visualizzate le traduzioni runtime durante il caricamento. | `object` | Sì | Vedi sotto | ### Prestazioni [#performance-options] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | --------------------------------------------------- | ----------------------------------------------------- | -------- | ----------- | ----------- | | [`maxConcurrentRequests`](#max-concurrent-requests) | Numero massimo di richieste di traduzione simultanee. | `number` | Sì | `100` | | [`maxBatchSize`](#max-batch-size) | Numero massimo di traduzioni per batch. | `number` | Sì | `25` | | [`batchInterval`](#batch-interval) | Millisecondi tra le richieste inviate in batch. | `number` | Sì | `50` | ### Build e integrazione [#build-options] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------- | ----------- | ----------- | | [`experimentalCompilerOptions`](#compiler-options) | Impostazioni del plugin del compilatore. | `object` | Sì | Vedi sotto | | [`headersAndCookies`](#headers-and-cookies) | Nomi personalizzati dell'header e del cookie dell'impostazione regionale. | `object` | Sì | Vedi sotto | | [`getLocalePath`](#request-function-paths) | Percorso di una funzione [`getLocale`](/docs/node/reference/functions/get-locale) personalizzata. | `string` | Sì | — | | [`getRegionPath`](#request-function-paths) | Percorso di una funzione `getRegion` personalizzata. | `string` | Sì | — | | [`pathRegex`](#path-regex) | Limita il middleware i18n ai pathname che corrispondono. | `string` | Sì | — | | [`eslint`](#eslint-options) | Genera la configurazione ESLint di General Translation. | `boolean` | Sì | `true` | | [`eslintSeverity`](#eslint-options) | Livello di severità delle regole ESLint generate. | `'error' \| 'warn'` | Sì | `'warn'` | | [`overwriteESLintConfig`](#eslint-options) | Sovrascrive un file `eslint.config.mjs` esistente. | `boolean` | Sì | `false` | ### `defaultLocale` [#default-locale] **Tipo** `string` · **Facoltativo** · **Predefinito** `en` L'impostazione regionale sorgente della tua app. Viene usata come fallback quando manca una traduzione. ### `locales` [#locales] **Tipo** `string[]` · **Facoltativo** · **Predefinito** `[]` Le locales di destinazione in cui tradurre. Le richieste per un'impostazione regionale non supportata usano prima la corrispondenza più vicina, poi `defaultLocale`. Scegli tra le [locales supportate](/docs/platform/dashboard/reference/supported-locales). ### `ignoreBrowserLocales` [#ignore-browser-locales] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `false` Quando è `true`, le preferenze `Accept-Language` del browser vengono ignorate durante il rilevamento dell'impostazione regionale. ### `disableInvalidLocaleWarning` [#disable-invalid-locale-warning] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `false` Quando è `true`, gli avvisi relativi a impostazioni regionali non valide nelle richieste non vengono mostrati. ### `description` [#description] **Tipo** `string` · **Facoltativo** Una descrizione in linguaggio naturale della tua app. Viene inviata come contesto per migliorare la qualità della traduzione. ### `runtimeUrl` [#runtime-url] **Tipo** `string | null` · **Facoltativo** · **Predefinito** runtime di General Translation URL di base dell'API di General Translation usata per la traduzione su richiesta. Impostalo su una stringa vuota per disattivare completamente la runtime translation. ### `cacheUrl` [#cache-url] **Type** `stringa | null` · **Opzionale** · **Predefinito** CDN di General Translation URL da cui vengono fornite le traduzioni memorizzate nella cache. Impostala su un host di cache personalizzato oppure su `null` per disattivare il caricamento remoto. ### `cacheExpiryTime` [#cache-expiry-time] **Tipo** `number` · **Facoltativo** · **Predefinito** `60000` Millisecondi prima della scadenza delle traduzioni memorizzate nella cache locale. Questo valore predefinito si applica al caricamento remoto in Production senza una chiave di sviluppo. ### `loadTranslationsPath` [#load-translations-path] **Tipo** `string` · **Facoltativo** Percorso di un file `loadTranslations` personalizzato per le [traduzioni locali](#translations). Per impostazione predefinita, il plugin individua automaticamente un file `loadTranslations.[js|ts]` nella radice del progetto o in `src/`. ### `loadDictionaryPath` [#load-dictionary-path] **Type** `string` · **Facoltativo** Percorso di un file `loadDictionary` personalizzato. Per impostazione predefinita, il plugin individua automaticamente un file `loadDictionary.[js|ts]` nella radice del progetto o in `src/`. ### `dictionary` [#dictionary] **Tipo** `string` · **Facoltativo** Percorso del file del dizionario. I file denominati `dictionary.[js|ts|json]` nella radice del progetto o in `src/` vengono individuati automaticamente. ### `config` [#config-path] **Tipo** `stringa` · **Facoltativo** · **Predefinito** `./gt.config.json` Percorso del file `gt.config.json` da caricare. ### `renderSettings` [#render-settings] **Tipo** `{ method: 'skeleton' | 'replace' | 'default'; timeout?: number }` · **Facoltativo** Controlla come viene visualizzato il contenuto mentre viene caricata una traduzione runtime. Si applica solo alle traduzioni eseguite on demand; le traduzioni memorizzate nella cache vengono visualizzate immediatamente. * `method` — uno dei seguenti: * `skeleton` — non visualizza nulla (un frammento) durante l'attesa. * `replace` — visualizza il contenuto nella lingua predefinita durante l'attesa. * `default` — si comporta come `replace` per i locales della stessa lingua (come `en-US` e `en-GB`) e come `skeleton` per lingue diverse. * `timeout` — millisecondi prima che il metodo di rendering vada in timeout e ricada sul contenuto originale. Il valore predefinito è `8000` in sviluppo e `12000` in produzione. ```ts title="next.config.ts" export default withGTConfig(nextConfig, { renderSettings: { method: 'skeleton', timeout: 10000, }, }); ``` ### `maxConcurrentRequests` [#max-concurrent-requests] **Type** `number` · **Facoltativo** · **Predefinito** `100` Numero massimo di richieste di traduzione contemporanee all'API di General Translation. ### `maxBatchSize` [#max-batch-size] **Tipo** `number` · **Facoltativo** · **Predefinito** `25` Numero massimo di traduzioni raggruppate in un'unica richiesta batch. ### `batchInterval` [#batch-interval] **Tipo** `number` · **Facoltativo** · **Predefinito** `50` Millisecondi di attesa tra richieste di traduzione in batch, per controllare la frequenza delle richieste. ### `experimentalCompilerOptions` [#compiler-options] **Tipo** `object` · **Facoltativo** Impostazioni per il plugin del compilatore che analizza il codice sorgente in fase di build. Campi: | Campo | Descrizione | Tipo | Predefinito | | -------------------- | ----------------------------------------------------- | ---------------------------------------------------- | ----------- | | `type` | Quale plugin del compilatore usare. | `'babel' \| 'swc' \| 'none'` | `'none'` | | `logLevel` | Livello di verbosità dei log del compilatore. | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | | `compileTimeHash` | Precalcola gli hash di traduzione in fase di build. | `boolean` | `true` | | `disableBuildChecks` | Disabilita i controlli di convalida in fase di build. | `boolean` | `false` | ### `headersAndCookies` [#headers-and-cookies] **Tipo** `object` · **Facoltativo** Sovrascrive i nomi di header e cookie usati da `gt-next` per trasmettere l'impostazione regionale e lo stato correlato della richiesta. Campi: `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName` e `resetLocaleCookieName`. Per impostazione predefinita, ciascuno usa il nome standard della libreria. ### Percorsi delle funzioni della richiesta [#request-function-paths] **Tipo** `string` · **Facoltativo** `getLocalePath` e `getRegionPath` puntano a implementazioni personalizzate di `getLocale` e `getRegion`, permettendoti di definire come vengono determinate l'impostazione regionale e la regione della richiesta. ### `pathRegex` [#path-regex] **Tipo** `string` · **Facoltativo** Una stringa sorgente che rappresenta un'espressione regolare JavaScript. Se impostata, il middleware i18n e il boundary di routing delle impostazioni regionali lato client vengono eseguiti solo sui pathname che corrispondono all'espressione — ad esempio, `^/(?!uk(?:/|$)).*` per escludere tutto ciò che si trova sotto `/uk`. Un'espressione non valida genera un errore in fase di build. Questa opzione si imposta qui, in `withGTConfig`, non in [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware); il plugin la inoltra al middleware in fase di build. **Gestisci manualmente gli alias delle impostazioni regionali:** I percorsi filtrati non passano dalla normalizzazione delle impostazioni regionali. Se le `locales` configurate sono `en`, `en-GB` e `fr`, il segmento di percorso `uk` non viene riconosciuto come `en-GB`. Una funzione `getLocale()` personalizzata deve restituire `en-GB` per `uk`: ```ts title="getLocale.ts" import { locale } from 'next/root-params'; export default async function getLocale() { const pathnameLocale = await locale(); if (pathnameLocale === 'uk') return 'en-GB'; return pathnameLocale; } ``` Applica la stessa mappatura prima di chiamare `registerLocale()`: ```ts registerLocale(locale === 'uk' ? 'en-GB' : locale); ``` Se `getLocale()` o `registerLocale()` ricevono un'impostazione regionale sconosciuta, `gt-next` mostra un avviso e usa `defaultLocale` come fallback. ### Opzioni di ESLint [#eslint-options] * `eslint` (`boolean`, default `true`) — genera la configurazione ESLint di General Translation durante la configurazione iniziale. * `eslintSeverity` (`'error' | 'warn'`, default `'warn'`) — livello di severità delle regole generate. * `overwriteESLintConfig` (`boolean`, default `false`) — consente di sovrascrivere un file `eslint.config.mjs` esistente. Per le regole in sé, vedi [Linting del codice](/docs/react/guides/linting-your-code). ## Traduzioni locali vs. traduzioni dalla CDN [#translations] Per impostazione predefinita, `gt-next` recupera le traduzioni dalla CDN di General Translation a runtime: i contenuti tradotti vi vengono caricati automaticamente quando esegui `npx gt translate`. In alternativa, puoi includere le traduzioni nel bundle della tua app e caricarle localmente. Le traduzioni locali si caricano più velocemente e funzionano offline, a costo di un bundle più grande e di una nuova distribuzione per ogni modifica ai contenuti. Per usarle, aggiungi un file `loadTranslations` che restituisce le traduzioni di un'impostazione regionale: ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`../public/_gt/${locale}.json`); return translations.default; } ``` `withGTConfig` rileva automaticamente un file `loadTranslations.[js|ts]` nella radice del progetto o nella directory `src/` (oppure imposta [`loadTranslationsPath`](#load-translations-path) in modo esplicito). Quindi punta la CLI alla stessa directory, così `npx gt translate` vi scriverà i file. Consulta [Archiviare localmente le traduzioni](/docs/react/guides/storing-translations) per il workflow completo. ## Restituisce [#returns] `withGTConfig` restituisce un oggetto `NextConfig` arricchito con le impostazioni di General Translation. Genera un errore in fase di build se la configurazione è in conflitto, se manca una chiave API obbligatoria, se viene utilizzata un'impostazione regionale non valida con i servizi di General Translation o se è presente una chiave di sviluppo in produzione.