# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuration URL: https://generaltranslation.com/fr/docs/react/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt 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 ces champs communs : | 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]` | | [`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 | — | | [`_tagIds`](#tag-ids) | Expose le hachage de traduction de chaque [``](/docs/react/reference/components/t) en tant qu’attribut DOM `data-_gt-hash`. | `boolean` | Oui | `false` | ### `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 des traductions, 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. Il accepte également ces champs réservés au navigateur : | Option | Description | Type | Facultatif | Par défaut | | ----------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------- | ---------- | | `locale` | Paramètre régional initial explicite. Ignore la détection lorsqu’il est défini. | `string` | Oui | Détecté | | `region` | Code de région initial pour le formatage tenant compte de la région. | `string` | Oui | — | | `enableI18n` | Traduit le contenu. Lorsque défini sur `false`, affiche le paramètre régional source. | `boolean` | Oui | `true` | | [`htmlTagOptions`](#htmltagoptions) | Champ de compatibilité qui ne met pas automatiquement à jour l’élément HTML. | `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` | Oui | — | ```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. Mettez à jour les attributs `lang` et `dir` de l’élément `` dans votre application lorsque le paramètre régional change. #### `htmlTagOptions` **Type** `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` · **Facultatif** Champ de compatibilité réservé aux navigateurs, accepté par `initializeGTSPA`. Le fait de le transmettre ne met pas automatiquement à jour les attributs `lang` ou `dir` de l’élément `` lorsque le paramètre régional change ; mettez ces attributs à jour dans votre application. ## `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 | — | | [`_tagIds`](#tag-ids) | Expose le hachage de traduction de chaque [``](/docs/react/reference/components/t) sous forme d’attribut DOM `data-_gt-hash`. | `boolean` | Oui | `false` | | [`_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[]` · **Facultatif** 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`. ## `_tagIds` [#tag-ids] **Type** `boolean` · **Facultatif** · **Par défaut** `false` Active l’ajout d’identifiants DOM aux sorties affichées de [``](/docs/react/reference/components/t) et [``](/docs/react/nextjs/reference/components/tx) dans `gt-react`, `gt-next` et `gt-tanstack-start`. Des outils tels que la relecture localisée et l’assurance qualité en contexte utilisent l’attribut `data-_gt-hash` pour associer un nœud affiché à sa traduction. Définissez `_tagIds` dans le fichier de configuration partagé, puis transmettez cette configuration à [`initializeGT`](#initialize) ou [`initializeGTSPA`](#initialize-spa). Le plugin `withGTConfig` lit le même fichier dans Next.js : ```json title="gt.config.json" { "_tagIds": true } ``` La valeur doit être exactement `true`. Toute autre valeur, y compris une valeur non booléenne évaluée comme vraie, laisse le tagging désactivé. React Native accepte le champ de configuration partagé, mais ignore le tagging du DOM. **L’activation de cette option peut ajouter des éléments d’encapsulation.** L’injection de `` est limitée au strict nécessaire : * **Un seul élément hôte** (par exemple `…`) est annoté sur place. Aucun élément d’encapsulation n’est ajouté : le balisage reste donc valide dans des parents restreints tels que ``, `