# General Translation React SDKs (gt-react, gt-next): Configurazione URL: https://generaltranslation.com/it/docs/react/reference/config.mdx --- title: Configurazione description: Configura General Translation nell'ecosistema React con il file `gt.config.json` condiviso e l'inizializzazione runtime. Riferimento API per `gt.config.json`. --- General Translation si configura in due punti: con un file `gt.config.json`, che contiene le impostazioni relative alle impostazioni regionali e ai file condivise con la [CLI](/docs/cli/reference/config), e con una fase di setup runtime che carica questa configurazione prima del primo rendering. Il file `gt.config.json` è lo stesso in tutto l'ecosistema React; il setup runtime varia invece in base al framework. *Il riferimento a `gt.config.json` in questa pagina è condiviso tra `gt-react`, `gt-next`, `gt-tanstack-start` e `gt-react-native`. Le funzioni di inizializzazione ([`initializeGT`](#initialize), [`initializeGTSPA`](#initialize-spa)) sono per `gt-react`; anche `gt-tanstack-start` e `gt-react-native` usano `initializeGT`.* *Nota: `gt-next` non usa queste funzioni di inizializzazione — legge la configurazione tramite il plugin `withGTConfig`, documentato nella sezione Next.js.* ## Panoramica [#overview] Un'app `gt-react` renderizzata lato server si configura in tre passaggi: inizializzare la libreria, caricare le traduzioni dell'impostazione regionale attiva e avvolgere l'albero in [``](/docs/react/reference/components/gt-provider). * **Inizializza** con [`initializeGT`](#initialize) per le configurazioni renderizzate lato server. Le app a pagina singola usano [`initializeGTSPA`](#initialize-spa), che rileva anche l'impostazione regionale attiva dai cookie e dal browser. * **Carica le traduzioni** per l'impostazione regionale attiva con [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot). * **Fornisci** l'impostazione regionale e le traduzioni ai tuoi componenti con [``](/docs/react/reference/components/gt-provider). ```tsx title="src/routes/root.tsx" import { initializeGT, getTranslationsSnapshot, parseLocale } from 'gt-react'; import gtConfig from '../../gt.config.json'; const loadTranslations = (locale: string) => import(`../_gt/${locale}.json`).then((m) => m.default); initializeGT({ ...gtConfig, loadTranslations }); export async function loadRoot(request: Request) { const locale = parseLocale(request); return { locale, translations: await getTranslationsSnapshot(locale), }; } ``` Il file `gt.config.json` contiene le impostazioni condivise relative all'impostazione regionale e ai file. Sia la chiamata di inizializzazione sia la CLI leggono gli stessi valori, quindi tienili in un unico posto. ## Inizializzazione [#initialization] | Funzione | Descrizione | Tipo | Facoltativo | Predefinito | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ----------- | ----------- | ----------- | | [`initializeGT`](#initialize) | Inizializza senza rilevamento dell'impostazione regionale del browser, per app con rendering lato server. | `function` | No | — | | [`initializeGTSPA`](#initialize-spa) | Inizializza una single-page app, incluso il rilevamento dell'impostazione regionale del browser. | `function` | No | — | Entrambe le funzioni accettano i campi riportati di seguito. Condividono le stesse opzioni, tranne che solo `initializeGTSPA` esegue il rilevamento dell'impostazione regionale del browser. | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- | ----------------- | | `defaultLocale` | Impostazione regionale sorgente da cui tradurre. | `stringa` | Sì | `en` | | `locales` | Impostazioni regionali di destinazione supportate. | `stringa[]` | Sì | `[defaultLocale]` | | `locale` | Impostazione regionale iniziale esplicita. Se impostata, non esegue il rilevamento. | `stringa` | Sì | Rilevata | | [`loadTranslations`](/docs/react/reference/functions/load-translations) | Loader che restituisce le traduzioni per un'impostazione regionale. Documentazione: [`loadTranslations`](/docs/react/reference/functions/load-translations). | `(locale: stringa) => Promise` | Sì | GT CDN | | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) | Loader che restituisce un dizionario per un'impostazione regionale. Documentazione: [`loadDictionary`](/docs/react/reference/functions/load-dictionary). | `(locale: stringa) => Promise` | Sì | — | | `dictionary` | Dizionario inline, come alternativa a `loadDictionary`. | `object` | Sì | — | | `projectId` | ID progetto di General Translation per CDN e traduzione di sviluppo. | `stringa` | Sì | — | | `devApiKey` | Chiave API di sviluppo per la traduzione su richiesta e l'hot reload. | `stringa` | Sì | — | | `apiKey` | Chiave API di produzione. Nel browser, è preferibile usare una `devApiKey`. | `stringa` | Sì | — | | `cacheUrl` | Host personalizzato per le traduzioni. `null` disabilita il caricamento remoto. | `stringa \| null` | Sì | GT CDN | | `runtimeUrl` | Host della traduzione runtime, usato per la traduzione di sviluppo. | `stringa \| null` | Sì | GT runtime | | `customMapping` | Alias delle impostazioni regionali e override delle proprietà. | `object` | Sì | — | | `region` | Codice regione iniziale per la formattazione sensibile alla regione. | `stringa` | Sì | — | | `enableI18n` | Traduce il contenuto. Quando è `false`, visualizza l'impostazione regionale sorgente. | `boolean` | Sì | `true` | | `htmlTagOptions` | Indica se sincronizzare gli attributi `lang` e `dir` di `` al cambio dell'impostazione regionale. | `object` | Sì | — | ### `initializeGT` [#initialize] **Type** `(config) => void` · **Obbligatorio** Inizializza la configurazione e la cache delle traduzioni senza il rilevamento dell'impostazione regionale del browser. Usalo nelle configurazioni con rendering lato server in cui il framework fornisce l'impostazione regionale della richiesta e le traduzioni. ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **Tipo** `(config) => Promise` · **Obbligatorio** Inizializza `gt-react` in un'applicazione single-page app. Chiamala una sola volta, prima del primo rendering. Crea la cache delle traduzioni, ricava l'impostazione regionale attiva dai cookie e dal browser e precarica le traduzioni. Disponibile solo nell'entry point del browser. ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` Poiché ricava l’impostazione regionale dall’ambiente, `initializeGTSPA` restituisce una Promise: attendila con `await` prima del rendering. Usa `htmlTagOptions` per controllare se gli attributi `lang` e `dir` dell’elemento `` vengono aggiornati quando l’impostazione regionale cambia: ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // predefinito: true updateHtmlDirTag: true, // predefinito: true }, }); ``` ## `gt.config.json` [#config-file] `gt.config.json` si trova nella radice del progetto e contiene le impostazioni relative all'impostazione regionale e ai file condivise con la CLI. Importalo e passane i campi all'inizializzazione. | Chiave | Descrizione | Tipo | Facoltativo | Predefinito | | ------------------------------------------ | --------------------------------------------------------------------- | ----------- | ----------- | ----------- | | [`projectId`](#project-id) | ID progetto di General Translation. | `stringa` | Sì | — | | [`defaultLocale`](#default-locale) | Impostazione regionale sorgente. | `stringa` | Sì | `en` | | [`locales`](#locales) | Impostazioni regionali di destinazione. | `stringa[]` | Sì | — | | [`customMapping`](#custom-mapping) | Alias delle impostazioni regionali e override delle proprietà. | `object` | Sì | — | | [`cacheUrl`](#cache-url) | URL di base per le traduzioni memorizzate nella cache. | `stringa` | Sì | GT CDN | | [`runtimeUrl`](#runtime-url) | URL di base per le traduzioni runtime (di sviluppo). | `stringa` | Sì | GT runtime | | [`stageTranslations`](#stage-translations) | Richiede una revisione prima che le traduzioni vadano in produzione. | `boolean` | Sì | `false` | | [`files`](#files) | Percorsi dei file di traduzione locale e flag di parsing. | `object` | Sì | — | | [`_versionId`](#version-id) | Identificatore interno della versione di traduzione. Non modificarlo. | `stringa` | Sì | — | ### `projectId` [#project-id] **Tipo** `stringa` · **Facoltativo** Identificatore univoco del tuo progetto in General Translation. Richiesto per la distribuzione tramite CDN e per la traduzione di sviluppo on-demand. ### `defaultLocale` [#default-locale] **Tipo** `stringa` · **Facoltativo** · **Predefinito** `en` L'impostazione regionale sorgente in cui è scritta l'interfaccia utente. Viene usata come fallback quando manca una traduzione. ### `locales` [#locales] **Tipo** `stringa[]` · **Facoltativo** Le impostazioni regionali di destinazione supportate dal tuo progetto, come i codici BCP 47 `['es', 'fr']`. ### `customMapping` [#custom-mapping] **Tipo** `object` · **Facoltativo** Alias delle impostazioni regionali e override delle proprietà, per rinominare o personalizzare la risoluzione e la visualizzazione delle impostazioni regionali. ### `cacheUrl` [#cache-url] **Tipo** `stringa` · **Facoltativo** · **Predefinito** GT CDN URL di base per recuperare le traduzioni dalla cache. Impostalo in modo che punti al tuo host oppure passa `null` nella chiamata di inizializzazione per disabilitare il caricamento remoto. ### `runtimeUrl` [#runtime-url] **Tipo** `stringa` · **Facoltativo** · **Predefinito** GT runtime URL di base del servizio di traduzione runtime. Si applica solo alle traduzioni di sviluppo. ### `stageTranslations` [#stage-translations] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `false` Quando è `true`, lo strumento `gt` contrassegna le traduzioni come da revisionare. Devono essere approvate prima di poter essere distribuite in ambiente di produzione tramite [`gt translate`](/docs/cli/reference/commands/translate). ### `files` [#files] **Type** `object` · **Facoltativo** Specifica dove vengono scritte le traduzioni archiviate localmente, come alternativa all'archiviazione nel cloud. `files.gt.output` è un modello di percorso che contiene `[locale]` e `files.gt.parsingFlags` controlla il modo in cui il compilatore analizza il sorgente. ```json title="gt.config.json" { "files": { "gt": { "output": "src/_gt/[locale].json", "parsingFlags": { "enableAutoJsxInjection": true, "autoderive": true } } } } ``` * `enableAutoJsxInjection` (`boolean`, default `false`) — racchiude automaticamente il testo JSX traducibile nei componenti di traduzione in fase di build. Vedi [auto JSX injection](/docs/cli/guides/using-auto-jsx). * `autoderive` (`boolean`, default `false`) — tratta automaticamente i valori interpolati nelle chiamate a [`t()`](/docs/react/reference/functions/t-function), `gt()` e [`msg()`](/docs/react/reference/functions/msg) come chiamate a [`derive()`](/docs/react/reference/functions/derive). Vedi [autoderive](/docs/cli/guides/using-autoderive). Consulta il [riferimento della configurazione CLI](/docs/cli/reference/config) per lo `schema` completo di `files`. ### `_versionId` [#version-id] **Tipo** `stringa` · **Facoltativo** Identificatore interno usato dalla CLI per tenere traccia della versione della traduzione, consentendo di ripristinare traduzioni precedenti. Viene generato automaticamente — non modificarlo. Le key con prefisso underscore sono interne. ## Esempi [#examples] ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` ```tsx title="src/routes/root.tsx" import { GTProvider, initializeGT, getTranslationsSnapshot, parseLocale, } from 'gt-react'; import gtConfig from '../../gt.config.json'; const loadTranslations = (locale: string) => import(`../_gt/${locale}.json`).then((m) => m.default); initializeGT({ ...gtConfig, loadTranslations }); export async function loadRoot(request: Request) { const locale = parseLocale(request); return { locale, translations: await getTranslationsSnapshot(locale), }; } export function Root({ locale, translations, children }) { return ( {children} ); } ```