# General Translation React SDKs (gt-react, gt-next, gt-react-native): 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. * **Routing delle impostazioni regionali di Pages Router.** Quando è presente `nextConfig.i18n`, i relativi `locales` e `defaultLocale` dovrebbero corrispondere ai valori espliciti in `gt.config.json`. Una mancata corrispondenza genera un avviso in fase di build, ma non interrompe la build. L'ordine delle impostazioni regionali viene ignorato e il confronto di General Translation include `defaultLocale` nel proprio insieme effettivo di impostazioni regionali. Next.js fornisce l'impostazione regionale attiva alle funzioni dati di Pages Router. * **Le credenziali provengono dall'ambiente.** Non puoi passare `projectId`, `apiKey` o `devApiKey` come opzioni: impostali come variabili d'ambiente (vedi [Credenziali](#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`](/docs/react/reference/functions/load-translations) 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`](/docs/react/nextjs/reference/functions/get-region) 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`](/docs/react/reference/functions/load-translations) 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`](/docs/react/reference/functions/load-dictionary) 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` | | `enableAutoJsxInjection` | Avvolge automaticamente il JSX traducibile in fase di build. | `boolean` | `false` | Installa `@generaltranslation/compiler`, quindi imposta `enableAutoJsxInjection` qui oppure in `files.gt.parsingFlags` in `gt.config.json`. Preferisci `gt.config.json` per mantenere sincronizzati l'estrazione tramite CLI e le trasformazioni del compilatore; vedi [Uso dell'iniezione automatica di JSX](/docs/cli/guides/using-auto-jsx). In entrambi i casi, è necessario `type: 'babel'` perché `gt-next` carichi il compilatore: ```ts title="next.config.ts" export default withGTConfig(nextConfig, { experimentalCompilerOptions: { type: 'babel', enableAutoJsxInjection: true, }, }); ``` L'iniezione automatica di JSX funziona solo nelle build webpack. Esegui `next dev --webpack` durante lo sviluppo e `next build --webpack` in produzione. Next.js 16 usa Turbopack per impostazione predefinita; Turbopack disabilita il compilatore Babel e `type: 'swc'` o `type: 'none'` non supportano l'iniezione. In ogni caso, `gt-next` avvisa che l'iniezione è stata ignorata. ### `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. Quando il routing internazionalizzato di Next.js è configurato e `localeDetection` non è `false`, `gt-next` usa il cookie di preferenza standard `NEXT_LOCALE` anche se `localeCookieName` è personalizzato. Next.js legge quel cookie solo durante il rilevamento automatico dell'impostazione regionale. Impostando `nextConfig.i18n.localeDetection` su `false` viene mantenuto il nome del cookie General Translation configurato. **Modificato nella v11.1.3:** Il rilevamento dell'impostazione regionale di Pages Router ora segue `context.locale` di Next.js e allinea la persistenza lato client con `NEXT_LOCALE`. Imposta `localeDetection: false` per mantenere un cookie dell'impostazione regionale General Translation personalizzato. ### Percorsi delle funzioni della richiesta [#request-function-paths] **Tipo** `string` · **Facoltativo** `getLocalePath` e `getRegionPath` puntano a implementazioni personalizzate di [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) e [`getRegion`](/docs/react/nextjs/reference/functions/get-region), 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()`](/docs/react/nextjs/reference/functions/get-locale) 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()`](/docs/react/nextjs/reference/functions/register-locale): ```ts registerLocale(locale === 'uk' ? 'en-GB' : locale); ``` Se [`getLocale()`](/docs/react/nextjs/reference/functions/get-locale) o [`registerLocale()`](/docs/react/nextjs/reference/functions/register-locale) 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. 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`](/docs/cli/reference/commands/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`](/docs/react/reference/functions/load-translations) 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`](/docs/cli/reference/commands/translate) vi scriverà i file. Consulta [Archiviare localmente le traduzioni](/docs/react/guides/storing-translations) per il workflow completo. **Modificato nella v11.1.0:** le build webpack ora risolvono correttamente i file personalizzati [`loadDictionary`](/docs/react/reference/functions/load-dictionary), [`loadTranslations`](/docs/react/reference/functions/load-translations) e `dictionary`. Esegui l'aggiornamento dalla v11.0.x se ogni lookup del dizionario in webpack segnala una voce mancante nonostante i file siano presenti; Turbopack non era interessato. ## 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.