# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configurazione
URL: https://generaltranslation.com/it/docs/react/nextjs/config.mdx
Docs index: https://generaltranslation.com/llms.txt
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.    |

<Callout type="warn">
  **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`.
</Callout>

## Opzioni [#options]

Tutte le opzioni sono facoltative. Le opzioni relative all&#39;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&#39;API di General Translation. Una stringa vuota disabilita la traduzione runtime.       | `string \| null` | Sì          | `https://api.gtx.dev`   |
| [`cacheUrl`](#cache-url)                          | URL delle traduzioni memorizzate nella cache.                                                               | `string \| null` | Sì          | `https://cdn.gtx.dev`   |
| [`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&#39;header e del cookie dell&#39;impostazione regionale.                                   | `object`            | Sì          | Vedi sotto  |
| [`getLocalePath`](#request-function-paths)         | Percorso di una funzione [`getLocale`](/docs/react/nextjs/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ì          | —           |
| [`_tagIds`](#tag-ids)                              | Espone l&#39;hash di traduzione di ogni [`<T>`](/docs/react/reference/components/t) come attributo `data-_gt-hash`. | `boolean`           | Sì          | `false`     |
| [`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&#39;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&#39;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&#39;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** `https://api.gtx.dev`

URL di base dell&#39;API di General Translation usata per la traduzione su richiesta. Impostalo su una stringa vuota per disattivare completamente la traduzione runtime.

### `cacheUrl` [#cache-url]

**Type** `stringa | null` · **Opzionale** · **Predefinito** `https://cdn.gtx.dev`

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&#39;attesa.
  * `replace` — visualizza il contenuto nella lingua predefinita durante l&#39;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&#39;API di General Translation.

### `maxBatchSize` [#max-batch-size]

**Tipo** `number` · **Facoltativo** · **Predefinito** `25`

Numero massimo di traduzioni raggruppate in un&#39;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&#39;estrazione tramite CLI e le trasformazioni del compilatore; vedi [Uso dell&#39;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&#39;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&#39;iniezione. In ogni caso, `gt-next` avvisa che l&#39;iniezione è stata ignorata.

### `headersAndCookies` [#headers-and-cookies]

**Tipo** `object` · **Facoltativo**

Sovrascrive i nomi di header e cookie usati da `gt-next` per trasmettere l&#39;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&#39;impostazione regionale. Impostando `nextConfig.i18n.localeDetection` su `false` viene mantenuto il nome del cookie General Translation configurato.

<Callout type="info">
  **Modificato nella v11.1.3:** Il rilevamento dell&#39;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&#39;impostazione regionale General Translation personalizzato.
</Callout>

### 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&#39;impostazione regionale e la regione della richiesta.

### `pathRegex` [#path-regex]

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

Una stringa sorgente che rappresenta un&#39;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&#39;espressione — ad esempio, `^/(?!uk(?:/|$)).*` per escludere tutto ciò che si trova sotto `/uk`. Un&#39;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.

<Callout type="warn">
  **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&#39;impostazione regionale sconosciuta, `gt-next` mostra un avviso e usa `defaultLocale` come fallback.

  *Questi esempi usano* `next/root-params`*, disponibile in Next.js 15.5 e versioni successive. In Next.js 15.2–15.4, usa il fallback* `unstable_rootParams` *mostrato nella [guida al middleware App Router](/docs/react/nextjs/app-router-middleware#root-locale).*
</Callout>

### `_tagIds` [#tag-ids]

**Tipo** `boolean` · **Facoltativo** · **Predefinito** `false`

Abilita il tagging degli ID DOM del runtime React condiviso. Impostala in `gt.config.json` o passala a `withGTConfig`:

```ts title="next.config.ts"
export default withGTConfig(nextConfig, {
  _tagIds: true,
});
```

(Consulta il [riferimento condiviso su `_tagIds`](/docs/react/reference/config#tag-ids) per i framework supportati, il comportamento esatto del markup e l&#39;esclusione di React Native).

### 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&#39;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.

<Callout type="info">
  **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&#39;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.
</Callout>

## 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&#39;impostazione regionale non valida con i servizi di General Translation o se è presente una chiave di sviluppo in produzione.

## Sitemap

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