# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configurazione URL: https://generaltranslation.com/it/docs/react/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt Description: Configura l'ecosistema React con il file gt.config.json condiviso e l'inizializzazione runtime. Riferimento 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 questi campi condivisi: | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- | ----------------- | | `defaultLocale` | Impostazione regionale sorgente da cui tradurre. | `stringa` | Sì | `en` | | `locales` | Impostazioni regionali di destinazione supportate. | `stringa[]` | Sì | `[defaultLocale]` | | [`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`](/docs/react/reference/functions/load-dictionary). | `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ì | — | | [`_tagIds`](#tag-ids) | Espone ogni hash di traduzione di [``](/docs/react/reference/components/t) come attributo DOM `data-_gt-hash`. | `boolean` | Sì | `false` | ### `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. Accetta inoltre questi campi disponibili solo nel browser: | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------- | ----------- | | `locale` | Impostazione regionale iniziale esplicita. Se impostata, salta il rilevamento. | `string` | Sì | Rilevata | | `region` | Codice regione iniziale per la formattazione in base alla regione. | `string` | Sì | — | | `enableI18n` | Traduce il contenuto. Quando è `false`, renderizza l'impostazione regionale sorgente. | `boolean` | Sì | `true` | | [`htmlTagOptions`](#htmltagoptions) | Campo di compatibilità che non aggiorna automaticamente l'elemento HTML. | `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` | Sì | — | ```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. Aggiorna gli attributi `lang` e `dir` dell’elemento `` nella tua app quando l’impostazione regionale cambia. #### `htmlTagOptions` **Tipo** `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` · **Facoltativo** Campo di compatibilità disponibile solo nel browser e accettato da `initializeGTSPA`. Passarlo non aggiorna automaticamente gli attributi `lang` o `dir` dell'elemento `` quando cambia l'impostazione regionale; aggiorna questi attributi nella tua app. ## `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ì | — | | [`localeRouting`](#locale-routing) | Mantieni l'impostazione regionale attiva nel pathname. | `boolean` | Sì | Specifico del framework | | [`customMapping`](#custom-mapping) | Alias delle impostazioni regionali e override delle proprietà. | `object` | Sì | — | | [`cacheUrl`](#cache-url) | URL di base per la traduzione dalla 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ì | — | | [`_tagIds`](#tag-ids) | Espone ogni hash di traduzione [``](/docs/react/reference/components/t) come attributo DOM `data-_gt-hash`. | `boolean` | Sì | `false` | | [`_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']`. ### `localeRouting` [#locale-routing] **Tipo** `boolean` · **Facoltativo** · **Predefinito** specifico del framework Controlla gli URL con prefisso dell'impostazione regionale in TanStack Start. È opt-in e il valore predefinito è `false`. Questa opzione non definisce le route: configura parametri di percorso facoltativi `/{-$locale}` o riscritture degli URL affinché TanStack Router accetti sia URL senza prefisso sia URL con prefisso dell'impostazione regionale. Consulta la [guida alla configurazione di TanStack Start](/docs/react/tanstack-start/setup#locale-routing). Una volta abilitato, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) dà priorità al primo segmento di percorso supportato, l'impostazione regionale predefinita rimane senza prefisso e le modifiche dell'impostazione regionale lato client ricaricano il pathname corrispondente. Next.js configura il routing separatamente tramite [`createNextMiddleware({ localeRouting })`](/docs/react/nextjs/reference/functions/create-next-middleware), che per impostazione predefinita è `true`. Questa opzione non influisce sulle semplici SPA React né su React Native. ### `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`. ## `_tagIds` [#tag-ids] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `false` Abilita l'aggiunta di ID DOM all'output renderizzato di [``](/docs/react/reference/components/t) e [``](/docs/react/nextjs/reference/components/tx) in `gt-react`, `gt-next` e `gt-tanstack-start`. Strumenti come il replay localizzato e il QA contestuale usano l'attributo `data-_gt-hash` per ricondurre un nodo renderizzato alla relativa traduzione. Imposta `_tagIds` nel file di configurazione condiviso, quindi passa la configurazione a [`initializeGT`](#initialize) o [`initializeGTSPA`](#initialize-spa). Il plugin `withGTConfig` legge lo stesso file in Next.js: ```json title="gt.config.json" { "_tagIds": true } ``` Il valore deve essere letteralmente `true`. Qualsiasi altro valore, incluso un valore truthy non booleano, lascia il tagging disattivato. React Native accetta il campo di config condiviso ma non esegue il tagging del DOM. **L'abilitazione di questa opzione può aggiungere elementi wrapper.** L'iniezione di `` è ridotta al minimo necessario: * **Un singolo elemento host** (ad esempio `…`) viene annotato in-place. Non viene aggiunto alcun wrapper, quindi il markup rimane valido all'interno di elementi padre con restrizioni come ``, `