# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuration URL: https://generaltranslation.com/fr/docs/react/reference/config.mdx --- title: Configuration description: Configurez l’écosystème React avec le fichier partagé gt.config.json et l’initialisation à l’exécution. Référence pour gt.config.json. --- General Translation se configure à deux niveaux : un fichier `gt.config.json`, qui contient le paramètre régional et les paramètres de fichier partagés avec la [CLI](/docs/cli/reference/config), et une étape d’initialisation à l’exécution, qui charge cette configuration avant le premier rendu. Le fichier `gt.config.json` est le même dans tout l’écosystème React ; en revanche, l’initialisation à l’exécution varie selon le framework. *La référence de `gt.config.json` sur cette page est partagée entre `gt-react`, `gt-next`, `gt-tanstack-start` et `gt-react-native`. Les fonctions d’initialisation ([`initializeGT`](#initialize), [`initializeGTSPA`](#initialize-spa)) sont destinées à `gt-react` ; `gt-tanstack-start` et `gt-react-native` utilisent également `initializeGT`.* *Remarque : `gt-next` n’utilise pas ces fonctions d’initialisation — il lit la configuration via le plugin `withGTConfig`, documenté dans la section Next.js.* ## Vue d’ensemble [#overview] Une application `gt-react` avec rendu côté serveur se configure en trois étapes : initialiser la bibliothèque, charger les traductions du paramètre régional actif et envelopper l’arbre de composants dans [``](/docs/react/reference/components/gt-provider). * **Initialiser** avec [`initializeGT`](#initialize) pour les configurations avec rendu côté serveur. Les applications monopages utilisent [`initializeGTSPA`](#initialize-spa), qui détermine aussi le paramètre régional actif à partir des cookies et du navigateur. * **Charger les traductions** du paramètre régional actif avec [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot). * **Fournir** le paramètre régional et les traductions à vos composants avec [``](/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), }; } ``` Le fichier `gt.config.json` contient les paramètres partagés du paramètre régional et des fichiers. L’appel d’initialisation et la CLI utilisent les mêmes valeurs ; conservez-les donc au même endroit. ## Initialisation [#initialization] | Fonction | Description | Type | Facultatif | Par défaut | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------- | ---------- | ---------- | | [`initializeGT`](#initialize) | Initialise sans détection du paramètre régional du navigateur, pour les applications rendues côté serveur. | `function` | Non | — | | [`initializeGTSPA`](#initialize-spa) | Initialise une application monopage, avec détection du paramètre régional du navigateur. | `function` | Non | — | Les deux fonctions acceptent les champs ci-dessous. Elles partagent les mêmes options, sauf que seule `initializeGTSPA` effectue la détection du paramètre régional du navigateur. | Option | Description | Type | Facultatif | Par défaut | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------- | ----------------- | | `defaultLocale` | Paramètre régional source à partir duquel traduire. | `string` | Oui | `en` | | `locales` | Locales cibles pris en charge. | `string[]` | Oui | `[defaultLocale]` | | `locale` | Paramètre régional initial explicite. Ignore la détection lorsqu’il est défini. | `string` | Oui | Détecté | | [`loadTranslations`](/docs/react/reference/functions/load-translations) | Loader renvoyant les traductions d’un paramètre régional. Documentation : [`loadTranslations`](/docs/react/reference/functions/load-translations). | `(locale: string) => Promise` | Oui | GT CDN | | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) | Loader renvoyant un dictionnaire pour un paramètre régional. Documentation : [`loadDictionary`](/docs/react/reference/functions/load-dictionary). | `(locale: string) => Promise` | Oui | — | | `dictionary` | Dictionnaire inline, comme alternative à [`loadDictionary`](/docs/react/reference/functions/load-dictionary). | `object` | Oui | — | | `projectId` | ID de projet General Translation pour le CDN et la traduction de développement. | `string` | Oui | — | | `devApiKey` | Clé API de développement pour la traduction à la demande et le hot reload. | `string` | Oui | — | | `apiKey` | Clé API de production. Préférez une `devApiKey` dans le navigateur. | `string` | Oui | — | | `cacheUrl` | Hôte de traductions personnalisé. `null` désactive le chargement à distance. | `string \| null` | Oui | GT CDN | | `runtimeUrl` | Hôte de traduction au runtime, utilisé pour la traduction de développement. | `string \| null` | Oui | GT runtime | | `customMapping` | Alias de paramètres régionaux et surcharges de propriétés. | `object` | Oui | — | | `region` | Code de région initial pour un formatage tenant compte de la région. | `string` | Oui | — | | `enableI18n` | Traduit le contenu. Quand `false`, affiche le paramètre régional source. | `boolean` | Oui | `true` | | `htmlTagOptions` | Indique s’il faut synchroniser les attributs `lang` et `dir` de `` lors d’un changement de paramètre régional. | `object` | Oui | — | ### `initializeGT` [#initialize] **Type** `(config) => void` · **Obligatoire** Initialise la configuration et le cache des traductions sans détection du paramètre régional du navigateur. Utilisez-le dans des configurations rendues côté serveur, lorsque votre framework fournit le paramètre régional de la requête ainsi que les traductions. ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **Type** `(config) => Promise` · **Obligatoire** Initialise `gt-react` dans une application monopage. Appelez-la une seule fois, avant le premier rendu. Elle crée le cache de traduction, détermine le paramètre régional actif à partir des cookies et du navigateur, et précharge les traductions. Disponible uniquement dans le point d’entrée du navigateur. ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` Comme `initializeGTSPA` récupère le paramètre régional depuis l’environnement, il renvoie une promesse — attendez sa résolution avant d’effectuer le rendu. Utilisez `htmlTagOptions` pour contrôler si les attributs `lang` et `dir` de l’élément `` sont mis à jour lorsque le paramètre régional change : ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // par défaut : true updateHtmlDirTag: true, // par défaut : true }, }); ``` ## `gt.config.json` [#config-file] `gt.config.json` se trouve à la racine de votre projet et contient les paramètres de paramètre régional ainsi que les paramètres de fichiers partagés avec la CLI. Importez-le et transmettez ses champs à l’initialisation. | Clé | Description | Type | Facultatif | Par défaut | | ------------------------------------------ | --------------------------------------------------------------- | ---------- | ---------- | ----------------------- | | [`projectId`](#project-id) | ID du projet General Translation. | `string` | Oui | — | | [`defaultLocale`](#default-locale) | Paramètre régional source. | `string` | Oui | `en` | | [`locales`](#locales) | Locales cibles. | `string[]` | Oui | — | | [`localeRouting`](#locale-routing) | Conserver le paramètre régional actif dans le chemin d’accès. | `boolean` | Oui | Spécifique au framework | | [`customMapping`](#custom-mapping) | Alias de paramètres régionaux et surcharges de propriétés. | `object` | Oui | — | | [`cacheUrl`](#cache-url) | URL de base des traductions mises en cache. | `string` | Oui | GT CDN | | [`runtimeUrl`](#runtime-url) | URL de base des traductions à l’exécution (développement). | `string` | Oui | GT runtime | | [`stageTranslations`](#stage-translations) | Exige une révision avant la mise en production des traductions. | `boolean` | Oui | `false` | | [`files`](#files) | Chemins des fichiers de traduction locale et options d’analyse. | `object` | Oui | — | | [`_versionId`](#version-id) | Identifiant interne de version de traduction. Ne pas modifier. | `string` | Oui | — | ### `projectId` [#project-id] **Type** `string` · **Facultatif** Identifiant unique de votre projet dans General Translation. Requis pour la diffusion via CDN et la traduction à la demande en développement. ### `defaultLocale` [#default-locale] **Type** `string` · **Facultatif** · **Par défaut** `en` Le paramètre régional source de votre interface. Sert de contenu de secours lorsqu’une traduction est absente. ### `locales` [#locales] **Type** `string[]` · **Optionnel** Les locales cibles prises en charge par votre projet, sous forme de codes BCP 47 comme `['es', 'fr']`. ### `localeRouting` [#locale-routing] **Type** `boolean` · **facultatif** · **Par défaut** spécifique au framework Contrôle les URL préfixées par le paramètre régional dans TanStack Start. Cette fonctionnalité doit être activée explicitement et sa valeur par défaut est `false`. Cette option ne définit pas les routes : configurez des paramètres de chemin `/{-$locale}` facultatifs ou des réécritures d’URL afin que TanStack Router accepte à la fois les URL sans préfixe et celles préfixées par le paramètre régional. Consultez le [guide de configuration de TanStack Start](/docs/react/tanstack-start/setup#locale-routing). Une fois activée, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) donne la priorité au premier segment de chemin pris en charge, le paramètre régional par défaut reste sans préfixe et les changements de paramètre régional côté client rechargent le pathname correspondant. Next.js configure le routage séparément via [`createNextMiddleware({ localeRouting })`](/docs/react/nextjs/reference/functions/create-next-middleware), dont la valeur par défaut est `true`. Cette option n’affecte pas les SPAs React classiques ni React Native. ### `customMapping` [#custom-mapping] **Type** `object` · **Facultatif** Alias de paramètres régionaux et surcharges de propriétés, permettant de renommer ou de personnaliser la façon dont les paramètres régionaux sont résolus et affichés. ### `cacheUrl` [#cache-url] **Type** `string` · **Facultatif** · **Par défaut** GT CDN URL de base utilisée pour récupérer les traductions en cache. Définissez-la pour qu'elle pointe vers votre propre hôte, ou passez `null` lors de l'appel d'initialisation pour désactiver le chargement à distance. ### `runtimeUrl` [#runtime-url] **Type** `string` · **Facultatif** · **Par défaut** GT runtime URL de base du service de traduction à l’exécution. Cela s’applique uniquement aux traductions de développement. ### `stageTranslations` [#stage-translations] **Type** `boolean` · **Facultatif** · **Par défaut** `false` Lorsque cette option est définie sur `true`, l’outil `gt` met les traductions en attente de révision. Elles doivent être approuvées avant de pouvoir être déployées en production via [`gt translate`](/docs/cli/reference/commands/translate). ### `files` [#files] **Type** `object` · **Facultatif** Emplacement où sont enregistrées les traductions stockées localement, au lieu de les stocker dans le cloud. `files.gt.output` est un modèle de chemin contenant `[locale]`, et `files.gt.parsingFlags` contrôle la façon dont le compilateur analyse votre code source. ```json title="gt.config.json" { "files": { "gt": { "output": "src/_gt/[locale].json", "parsingFlags": { "enableAutoJsxInjection": true, "autoderive": true } } } } ``` * `enableAutoJsxInjection` (`boolean`, par défaut `false`) — encapsule automatiquement le texte JSX traduisible dans des composants de traduction lors de la build. Voir [l’injection automatique de JSX](/docs/cli/guides/using-auto-jsx). * `autoderive` (`boolean`, par défaut `false`) — traite automatiquement les valeurs interpolées dans les appels à [`t()`](/docs/react/reference/functions/t-function), `gt()` et [`msg()`](/docs/react/reference/functions/msg) comme des appels à [`derive()`](/docs/react/reference/functions/derive). Voir [autoderive](/docs/cli/guides/using-autoderive). Consultez la [référence de configuration du CLI](/docs/cli/reference/config) pour le schéma complet de `files`. ### `_versionId` [#version-id] **Type** `string` · **Facultatif** Identifiant interne utilisé par le CLI pour suivre la version des traductions, ce qui permet de revenir à des traductions antérieures. Il est généré automatiquement — ne le modifiez pas. Les clés préfixées par un trait de soulignement sont internes. ## Exemples [#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} ); } ```