# General Translation React SDKs (gt-react, gt-next): Configuration URL: https://generaltranslation.com/fr/docs/react/reference/config.mdx --- title: Configuration description: Configurez General Translation dans l’écosystème React avec le fichier partagé gt.config.json et l’initialisation à l’exécution. Référence d’API 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`. | `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` | Aliases de locales 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 | — | | [`customMapping`](#custom-mapping) | Alias de locales et remplacements 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']`. ### `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} ); } ```