# gt-next: General Translation Next.js SDK: withGTConfig
URL: https://generaltranslation.com/it/docs/next/api/config/with-gt-config.mdx
---
title: withGTConfig
description: Riferimento dell'API per withGTConfig(), in precedenza initGT()
---

## Panoramica

`withGTConfig` è il metodo principale per configurare la libreria `gt-next`.
Avvolge direttamente un oggetto `NextConfig`.

```js title="next.config.mjs"
import { withGTConfig } from 'gt-next/config';

const nextConfig = {
    // il tuo next.config.js esistente
}

export default withGTConfig(nextConfig, {
  // Opzioni di configurazione aggiuntive
});
```

<Callout>
  **Legacy**

  `initGT` è il metodo legacy per configurare la libreria `gt-next`. Restituisce una funzione di callback che viene poi invocata sull&#39;oggetto `NextConfig`.
  Le proprietà di entrambe le funzioni sono le stesse, con l&#39;eccezione che `withGTProps` richiede anche il passaggio di `NextConfig`.
</Callout>

Usa `withGTConfig` per:

* Configurare le lingue supportate e l&#39;impostazione regionale predefinita (ovvero la lingua di fallback).
* Impostare chiavi API e ID del progetto per accedere ai servizi GT.
* Impostare il comportamento di caricamento.
* Configurare le impostazioni di timeout.
* Configurare endpoint personalizzati.
* Personalizzare il comportamento della traduzione, la cache e l&#39;elaborazione delle richieste in batch.
* Configurare la verifica in fase di build tramite il plugin SWC.

<Callout>
  `withGTConfig` va usato nel file `next.config.js` per abilitare la funzionalità di traduzione.
</Callout>


## Riferimento

Per impostazione predefinita, `withGTConfig` cercherà un file `gt.config.json` nella stessa directory del file `next.config.js`.

Questo file JSON verrà caricato e unito alla configurazione passata a `withGTConfig`.

Per ulteriori informazioni sul file di configurazione, consulta il riferimento di [gt.config.json](/docs/next/api/config/gt-config-json).

<Callout>
  Lo strumento CLI leggerà la configurazione solo dal file `gt.config.json`, quindi
  ti consigliamo di usare il file `gt.config.json` come fonte di riferimento per la tua app.

  Le opzioni di configurazione aggiuntive non presenti nel file `gt.config.json` possono essere passate direttamente a `withGTConfig` come proprietà.
</Callout>

### Prop richieste

<TypeTable
  type={{
  "nextConfig": {
    type: 'NextConfig',
    optional: false,
  },
}}
/>

### Prop consigliate

<TypeTable
  type={{
  "defaultLocale?": {
      type: 'string',
      optional: true,
      default: "locales[0] || 'en'"
  },
  "locales?": {
      type: 'string[]',
      optional: true,
      default: 'undefined',
  },
  "description?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
}}
/>

| Prop            | Descrizione                                                                                                                                                                                                                                                                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultLocale` | Impostazione regionale predefinita dell&#39;applicazione. Se non ne viene specificata alcuna, l&#39;inglese verrà usato come lingua di fallback.                                                                                                                                                                                                          |
| `locales`       | Un elenco esclusivo delle impostazioni regionali supportate dall&#39;applicazione. Se arriva una richiesta per un&#39;impostazione regionale non supportata, verrà reindirizzata alla lingua successiva preferita dal browser tra quelle presenti nell&#39;elenco. Se non viene trovata alcuna corrispondenza, verrà usato `defaultLocale` come fallback. |
| `description`   | Una descrizione del sito in linguaggio naturale, usata per facilitare la traduzione.                                                                                                                                                                                                                                                                      |

### Prop avanzate

<TypeTable
  type={{
    "projectId?": {
            type: 'string',
            optional: true,
    },
    "apiKey?": {
            type: 'string',
            optional: true,
    },
    "devApiKey?": {
            type: 'string',
            optional: true,
    },
    "preferredModelProvider?": {
            type: '"anthropic" | "openai"',
            optional: true,
    },
    "runtimeUrl?": {
            type: 'string',
            optional: true,
    },
    "cacheUrl?": {
            type: 'string',
            optional: true,
    },
    "cacheExpiryTime?": {
        type: 'number',
        optional: true,
        default: 60000,
    },
    "renderSettings?": {
        type: 'RenderSettings',
        optional: true,
    },
    "maxConcurrentRequests?": {
        type: 'number',
        optional: true,
        default: 100,
    },
    "batchInterval?": {
        type: 'number',
        optional: true,
        default: 50,
    },
    "maxBatchSize?": {
        type: 'number',
        optional: true,
        default: 25,
    },
    "dictionary?": {
        type: 'string',
        optional: true,
    },

}}
/>

| Prop                     | Descrizione                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`              | ID del progetto, che puoi specificare qui oppure come variabile d&#39;ambiente.                                                                                                                                                                                                                                                                                                                |
| `apiKey`                 | Sebbene non sia consigliato, puoi specificare qui una chiave API. Puoi anche fornirla come variabile d&#39;ambiente.                                                                                                                                                                                                                                                                           |
| `devApiKey`              | Sebbene non sia consigliato, puoi specificare qui una chiave API di sviluppo. Puoi anche fornirla come variabile d&#39;ambiente.                                                                                                                                                                                                                                                               |
| `preferredModelProvider` | Il provider di modelli IA da usare come prima scelta. Al momento sono supportati solo [Anthropic](https://anthropic.com) e [OpenAI](https://openai.com). Lascia questo campo vuoto e individueremo il provider migliore caso per caso, per ogni traduzione. Nei periodi di utilizzo intenso o quando un provider è disabilitato, non possiamo garantire che venga usato il provider preferito. |
| `runtimeUrl`             | URL di base dell&#39;API GT. Per disabilitare la traduzione automatica, impostalo su una stringa vuota.                                                                                                                                                                                                                                                                                        |
| `cacheUrl`               | URL in cui vengono archiviate le traduzioni memorizzate nella cache. Può essere personalizzato in modo che punti a un server cache personalizzato.                                                                                                                                                                                                                                             |
| `cacheExpiryTime`        | Tempo, in millisecondi, prima della scadenza delle traduzioni memorizzate localmente nella cache.                                                                                                                                                                                                                                                                                              |
| `renderSettings`         | Oggetto che specifica il comportamento di caricamento per le traduzioni runtime.                                                                                                                                                                                                                                                                                                               |
| `maxConcurrentRequests`  | Numero massimo di richieste di traduzione simultanee consentite verso l&#39;API GT.                                                                                                                                                                                                                                                                                                            |
| `maxBatchSize`           | Numero massimo di traduzioni da raggruppare in batch prima di inviare una richiesta.                                                                                                                                                                                                                                                                                                           |
| `batchInterval`          | Intervallo, in millisecondi, tra le richieste di traduzione in batch. Aiuta a controllare la frequenza con cui vengono inviate le richieste.                                                                                                                                                                                                                                                   |
| `dictionary`             | Percorso facoltativo del file di configurazione del dizionario. Analogamente a `i18n`, accetta una stringa per specificare un percorso personalizzato. I dizionari chiamati `dictionary.js` (o `.jsx`, `.ts`, `.tsx` ecc.) e collocati nella root o nella cartella `src` sono supportati per impostazione predefinita.                                                                         |

### Restituisce

Un oggetto `NextConfig` che integra le impostazioni GT specificate.

### Eccezioni

Genera un `Error` se `projectId` non è specificato e vengono usati gli URL predefiniti, oppure se la chiave API è necessaria ma manca.

***

## Impostazioni di rendering

Le impostazioni di rendering controllano il comportamento delle traduzioni durante il caricamento.
Questo vale solo per le traduzioni eseguite a runtime.
Se la traduzione è memorizzata nella cache, il tempo di risposta è troppo basso per giustificare un comportamento di caricamento.

<TypeTable
  type={{
method: {
    description: 'Il metodo usato per eseguire il rendering della pagina.',
    type: '"skeleton" | "replace" | "default"',
    optional: false,
    default: "default"
},
timeout: {
    description: 'Il tempo in millisecondi prima che il metodo vada in timeout.',
    type: 'number',
    optional: true,
    default: 8000,
},
}}
/>

| Prop      | Descrizione                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| `method`  | Il metodo usato per eseguire il rendering della pagina. Le opzioni sono `skeleton`, `replace` e `default`. |
| `timeout` | Il tempo in millisecondi prima che il metodo vada in timeout. Il valore predefinito è 8000 ms.             |

### Metodi di rendering

* `skeleton`: Esegue il rendering di un frammento.
* `replace`: Esegue il rendering del contenuto nella lingua predefinita durante l&#39;attesa.
* `default`: Per le impostazioni regionali con la stessa lingua (ad es. `en-US` e `en-GB`), si comporta come `replace`. Per le impostazioni regionali con lingue diverse (ad es. `en-US` e `fr`), si comporta come `skeleton`.

### Timeout

I timeout si applicano solo alle traduzioni runtime, ovvero alle traduzioni che devono essere eseguite su richiesta perché non sono state memorizzate nella cache.

Per impostazione predefinita, i timeout sono impostati su 8 secondi.
Questa scelta progettuale serve ad agevolare gli utenti di vercel, che nel piano gratuito hanno un timeout predefinito di 10 secondi per le funzioni serverless.

***

## Esempi

### Impostazioni di rendering

Questo esempio configura `gt-next` per mostrare uno skeleton mentre attende il caricamento delle traduzioni.
Se la traduzione richiede più di 8 secondi, il metodo andrà in timeout e mostrerà il contenuto nella lingua predefinita.

```json title="gt.config.json"
{
  "defaultLocale": "en-US",
  "locales": ["en-US", "es", "fr"],
}
```

```js title="next.config.mjs" copy
import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Le altre configurazioni di Next.js
};

export default withGTConfig(nextConfig, {
  renderSettings: {
    method: 'skeleton',
    timeout: 10000,
  },
});
```

***

## Note

* `withGTConfig` integra le funzionalità di traduzione di GT nella tua app Next.js e deve essere usato nel file di configurazione principale.
* Parametri come `apiKey` e `projectId` possono essere impostati direttamente nella configurazione o come variabili d&#39;ambiente.
* Parametri avanzati come `renderSettings` e `_batchInterval` consentono un controllo preciso del comportamento e delle prestazioni della traduzione.

## Passaggi successivi

* Aggiungi [la traduzione al tuo processo di CD](/docs/next/tutorials/quickdeploy).