# General Translation React SDKs (gt-react, gt-next): Configuration URL: https://generaltranslation.com/fr/docs/react/nextjs/config.mdx --- title: Configuration description: Configurez General Translation dans une application Next.js avec le plugin `withGTConfig` de `gt-next/config`, ses options, et les traductions locales ou via CDN. Référence d’API de `withGTConfig`. --- `withGTConfig` est le plugin de configuration de `gt-next`. Encapsulez votre configuration Next.js avec lui dans `next.config` pour activer l’internationalisation au moment du build. Il lit votre fichier `gt.config.json`, le fusionne avec les options que vous transmettez ainsi qu’avec vos variables d’environnement, puis configure le compilateur, le chargement des traductions et le traitement des requêtes. Cette page documente le plugin et ses options. Pour les paramètres de paramètre régional et de fichiers partagés de `gt.config.json`, consultez la [référence de configuration `gt-react`](/docs/react/reference/config) ; pour le schéma `files` côté CLI, consultez la [référence de configuration de la CLI](/docs/cli/reference/config). ## Aperçu [#overview] Importez `withGTConfig` depuis `gt-next/config` et utilisez-le pour envelopper votre configuration Next.js. Vous pouvez passer des options en deuxième argument, mais la plupart des projets conservent plutôt les paramètres régionaux dans `gt.config.json`. ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; import type { NextConfig } from 'next'; const nextConfig: NextConfig = { // votre configuration Next.js existante }; export default withGTConfig(nextConfig, { defaultLocale: 'en', locales: ['es', 'fr', 'ja'], }); ``` `withGTConfig` doit être utilisé dans `next.config` — c’est le seul endroit où l’internationalisation est intégrée au processus de `build`. ## Fonctionnement [#how-it-works] * **Résolution de la configuration.** Par défaut, le plugin charge `./gt.config.json` (il recherche aussi `./.gt/gt.config.json` et `./.locadex/gt.config.json`). Les valeurs sont fusionnées selon l'ordre de priorité suivant : **options transmises > variables d'environnement > `gt.config.json` > valeurs par défaut.** Si une clé définie à la fois dans `gt.config.json` et dans les options a des valeurs différentes, le build génère une erreur de conflit ; conservez donc chaque valeur à un seul endroit. * **Les identifiants proviennent de l'environnement.** Vous ne pouvez pas transmettre `projectId`, `apiKey` ou `devApiKey` comme options — définissez-les comme variables d'environnement (voir [Identifiants](#credentials)). * **Normalisation des paramètres régionaux.** Lorsque les services de General Translation sont activés, les codes de langue sont normalisés au format canonique BCP 47, et les paramètres régionaux non valides provoquent une erreur lors du build. * **Livraison des traductions.** Si un fichier [`loadTranslations`](/docs/react/reference/functions/load-translations) est trouvé, les traductions sont chargées depuis votre bundle ; sinon, elles sont récupérées depuis le CDN de General Translation. Voir [Traductions locales ou via CDN](#translations). ## Identifiants [#credentials] Définissez votre ID de projet et vos clés API comme variables d’environnement, jamais comme options du plugin : | Variable | Description | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `GT_PROJECT_ID` (ou `NEXT_PUBLIC_GT_PROJECT_ID`) | Votre ID de projet General Translation. | | `GT_API_KEY` | Clé API de production (préfixée par `gtx-api-`), utilisée par la CLI et les builds de production. | | `GT_DEV_API_KEY` (ou `NEXT_PUBLIC_GT_DEV_API_KEY`) | Clé API de développement (préfixée par `gtx-dev-`), pour la traduction à la demande en développement. | *Avertissement : ne préfixez jamais une clé API de production avec `NEXT_PUBLIC_` et n’incluez pas de clé de développement en production : le build échoue si `GT_DEV_API_KEY` est présent avec `NODE_ENV=production`.* ## Options [#options] Toutes les options sont facultatives. Le plus souvent, les options de paramètre régional sont définies dans `gt.config.json` plutôt qu’ici. ### Options de paramètres régionaux [#locale-options] | Option | Description | Type | Facultatif | Par défaut | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | ---------- | ---------- | | [`defaultLocale`](#default-locale) | Paramètre régional source de votre application. | `string` | Oui | `en` | | [`locales`](#locales) | Paramètres régionaux cibles vers lesquels effectuer la traduction. | `string[]` | Oui | `[]` | | [`ignoreBrowserLocales`](#ignore-browser-locales) | Ignorer les paramètres régionaux préférés du navigateur lors de la détection. | `boolean` | Oui | `false` | | [`disableInvalidLocaleWarning`](#disable-invalid-locale-warning) | Masquer les avertissements concernant les paramètres régionaux de requête non valides. | `boolean` | Oui | `false` | | [`description`](#description) | Description en langage naturel de votre application, utilisée pour guider la traduction. | `string` | Oui | — | ### Livraison des traductions [#delivery-options] | Option | Description | Type | Facultatif | Par défaut | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------- | ---------- | ---------------------- | | [`runtimeUrl`](#runtime-url) | URL de base de l’API de General Translation. Une chaîne vide désactive la traduction à l’exécution. | `string \| null` | Oui | Runtime GT | | [`cacheUrl`](#cache-url) | URL des traductions mises en cache. | `string \| null` | Oui | CDN GT | | [`cacheExpiryTime`](#cache-expiry-time) | Délai en millisecondes avant l’expiration des traductions mises en cache localement. | `number` | Oui | `60000` | | [`loadTranslationsPath`](#load-translations-path) | Chemin vers le fichier `loadTranslations` personnalisé. | `string` | Oui | Résolu automatiquement | | [`loadDictionaryPath`](#load-dictionary-path) | Chemin vers le fichier [`loadDictionary`](/docs/react/reference/functions/load-dictionary) personnalisé. | `string` | Oui | Résolu automatiquement | | [`dictionary`](#dictionary) | Chemin vers votre fichier de dictionnaire. | `string` | Oui | Résolu automatiquement | | [`config`](#config-path) | Chemin vers le fichier `gt.config.json`. | `string` | Oui | `./gt.config.json` | ### Affichage [#rendering-options] | Option | Description | Type | Facultatif | Défaut | | ------------------------------------ | --------------------------------------------------------------------- | -------- | ---------- | --------------- | | [`renderSettings`](#render-settings) | Mode d’affichage des traductions à l’exécution pendant le chargement. | `object` | Oui | Voir ci-dessous | ### Performance [#performance-options] | Option | Description | Type | Facultatif | Par défaut | | --------------------------------------------------- | ----------------------------------------------------- | -------- | ---------- | ---------- | | [`maxConcurrentRequests`](#max-concurrent-requests) | Nombre maximal de requêtes de traduction simultanées. | `number` | Oui | `100` | | [`maxBatchSize`](#max-batch-size) | Nombre maximal de traductions par lot. | `number` | Oui | `25` | | [`batchInterval`](#batch-interval) | Nombre de millisecondes entre les requêtes par lots. | `number` | Oui | `50` | ### Compilation et intégration [#build-options] | Option | Description | Type | Facultatif | Par défaut | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------- | ---------- | --------------- | | [`experimentalCompilerOptions`](#compiler-options) | Options du plugin du compilateur. | `object` | Oui | Voir ci-dessous | | [`headersAndCookies`](#headers-and-cookies) | Noms personnalisés de l’en-tête HTTP et du cookie du paramètre régional. | `object` | Oui | Voir ci-dessous | | [`getLocalePath`](#request-function-paths) | Chemin vers une fonction [`getLocale`](/docs/node/reference/functions/get-locale) personnalisée. | `string` | Oui | — | | [`getRegionPath`](#request-function-paths) | Chemin vers une fonction `getRegion` personnalisée. | `string` | Oui | — | | [`pathRegex`](#path-regex) | Limiter le middleware i18n aux chemins d’URL correspondants. | `string` | Oui | — | | [`eslint`](#eslint-options) | Générer la configuration ESLint de General Translation. | `boolean` | Oui | `true` | | [`eslintSeverity`](#eslint-options) | Niveau de sévérité des règles ESLint générées. | `'error' \| 'warn'` | Oui | `'warn'` | | [`overwriteESLintConfig`](#eslint-options) | Écraser un fichier `eslint.config.mjs` existant. | `boolean` | Oui | `false` | ### `defaultLocale` [#default-locale] **Type** `string` · **Facultatif** · **Par défaut** `en` Le paramètre régional source de votre application. Il sert de contenu de secours lorsqu'une traduction n'est pas disponible. ### `locales` [#locales] **Type** `string[]` · **Facultatif** · **Par défaut** `[]` Les paramètres régionaux cibles dans lesquels traduire. Les requêtes pour un paramètre régional non pris en charge basculent vers la correspondance la plus proche, puis vers `defaultLocale`. Choisissez parmi les [paramètres régionaux pris en charge](/docs/platform/dashboard/reference/supported-locales). ### `ignoreBrowserLocales` [#ignore-browser-locales] **Type** `boolean` · **Facultatif** · **Par défaut** `false` Lorsque cette option vaut `true`, les préférences `Accept-Language` du navigateur sont ignorées lors de la détection du paramètre régional. ### `disableInvalidLocaleWarning` [#disable-invalid-locale-warning] **Type** `boolean` · **Facultatif** · **Valeur par défaut** `false` Lorsque cette valeur est `true`, les avertissements concernant les paramètres régionaux de requête invalides sont supprimés. ### `description` [#description] **Type** `string` · **Facultatif** Une description en langage naturel de votre application. Elle est envoyée à titre de contexte afin d’améliorer la qualité des traductions. ### `runtimeUrl` [#runtime-url] **Type** `string | null` · **Facultatif** · **Par défaut** runtime de General Translation URL de base de l’API de General Translation utilisée pour la traduction à la demande. Définissez-la sur une chaîne vide pour désactiver complètement la traduction à l’exécution. ### `cacheUrl` [#cache-url] **Type** `string | null` · **Facultatif** · **Par défaut** CDN de General Translation URL depuis laquelle les traductions mises en cache sont servies. Faites-la pointer vers un hôte de cache personnalisé, ou définissez-la sur `null` pour désactiver le chargement distant. ### `cacheExpiryTime` [#cache-expiry-time] **Type** `number` · **Facultatif** · **Par défaut** `60000` Nombre de millisecondes avant que les traductions mises en cache localement n’expirent. Cette valeur par défaut s’applique au chargement distant en Production sans clé de développement. ### `loadTranslationsPath` [#load-translations-path] **Type** `string` · **Facultatif** Chemin vers un fichier `loadTranslations` personnalisé pour les [traductions locales](#translations). Par défaut, le plugin trouve automatiquement un fichier `loadTranslations.[js|ts]` à la racine de votre projet ou dans `src/`. ### `loadDictionaryPath` [#load-dictionary-path] **Type** `string` · **Facultatif** Chemin vers un fichier `loadDictionary` personnalisé. Par défaut, le plugin détecte automatiquement un fichier `loadDictionary.[js|ts]` à la racine de votre projet ou dans `src/`. ### `dictionary` [#dictionary] **Type** `string` · **Facultatif** Chemin vers votre fichier de dictionnaire. Les fichiers nommés `dictionary.[js|ts|json]` à la racine du projet ou dans `src/` sont automatiquement pris en compte. ### `config` [#config-path] **Type** `string` · **Facultatif** · **Par défaut** `./gt.config.json` Chemin du fichier `gt.config.json` à charger. ### `renderSettings` [#render-settings] **Type** `{ method: 'skeleton' | 'replace' | 'default'; timeout?: number }` · **Facultatif** Contrôle la manière dont le contenu s’affiche pendant le chargement d’une traduction à l’exécution. Cela s’applique uniquement aux traductions effectuées à la demande ; les traductions mises en cache s’affichent immédiatement. * `method` — l’une des valeurs suivantes : * `skeleton` — n’affiche rien (un fragment) pendant l’attente. * `replace` — affiche le contenu dans la langue par défaut pendant l’attente. * `default` — se comporte comme `replace` pour les paramètres régionaux d’une même langue (tels que `en-US` et `en-GB`), et comme `skeleton` pour des langues différentes. * `timeout` — nombre de millisecondes avant que la méthode d’affichage n’expire et revienne au contenu d’origine. La valeur par défaut est `8000` en développement et `12000` en production. ```ts title="next.config.ts" export default withGTConfig(nextConfig, { renderSettings: { method: 'skeleton', timeout: 10000, }, }); ``` ### `maxConcurrentRequests` [#max-concurrent-requests] **Type** `number` · **Facultatif** · **Par défaut** `100` Nombre maximal de requêtes de traduction simultanées vers l’API de General Translation. ### `maxBatchSize` [#max-batch-size] **Type** `number` · **Facultatif** · **Par défaut** `25` Nombre maximal de traductions regroupées dans une seule requête groupée. ### `batchInterval` [#batch-interval] **Type** `number` · **Facultatif** · **Par défaut** `50` Temps d’attente, en millisecondes, entre les requêtes de traduction par lots, afin de contrôler la fréquence des requêtes. ### `experimentalCompilerOptions` [#compiler-options] **Type** `object` · **Facultatif** Paramètres du plugin du compilateur qui analyse votre code source au moment du build. Champs : | Champ | Description | Type | Par défaut | | -------------------- | -------------------------------------------------------------- | ---------------------------------------------------- | ---------- | | `type` | Plugin du compilateur à utiliser. | `'babel' \| 'swc' \| 'none'` | `'none'` | | `logLevel` | Niveau de verbosité des logs du compilateur. | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | | `compileTimeHash` | Précalculer les hachages de traduction au moment du build. | `boolean` | `true` | | `disableBuildChecks` | Désactiver les vérifications de validation au moment du build. | `boolean` | `false` | ### `headersAndCookies` [#headers-and-cookies] **Type** `object` · **Facultatif** Redéfinit les noms d’en-tête et de cookie que `gt-next` utilise pour véhiculer le paramètre régional et l’état de requête associé. Champs : `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName` et `resetLocaleCookieName`. Chacun prend par défaut le nom standard de la bibliothèque. ### Chemins des fonctions de requête [#request-function-paths] **Type** `string` · **Facultatif** `getLocalePath` et `getRegionPath` pointent vers des implémentations personnalisées de `getLocale` et `getRegion`, vous permettant de redéfinir la manière dont le paramètre régional et la région de la requête sont résolus. ### `pathRegex` [#path-regex] **Type** `string` · **Facultatif** Chaîne source d’expression régulière JavaScript. Lorsqu’elle est définie, le middleware i18n et la limite de routage des paramètres régionaux côté client ne s’exécutent que sur les chemins qui correspondent à l’expression — par exemple, `^/(?!uk(?:/|$)).*` pour ignorer tout ce qui se trouve sous `/uk`. Une expression invalide provoque une erreur au build. Ce paramètre se définit ici, dans `withGTConfig`, et non dans [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware) ; le plugin le transmet au middleware au build. **Gérez manuellement les alias de paramètres régionaux :** Les chemins filtrés contournent la normalisation des paramètres régionaux. Si les locales configurées sont `en`, `en-GB` et `fr`, le segment de chemin `uk` n’est pas reconnu comme `en-GB`. Une fonction `getLocale()` personnalisée doit renvoyer `en-GB` pour `uk` : ```ts title="getLocale.ts" import { locale } from 'next/root-params'; export default async function getLocale() { const pathnameLocale = await locale(); if (pathnameLocale === 'uk') return 'en-GB'; return pathnameLocale; } ``` Appliquez le même mapping avant d’appeler `registerLocale()` : ```ts registerLocale(locale === 'uk' ? 'en-GB' : locale); ``` Si `getLocale()` ou `registerLocale()` reçoit un paramètre régional inconnu, `gt-next` affiche un avertissement et revient à `defaultLocale`. ### Options d’ESLint [#eslint-options] * `eslint` (`boolean`, default `true`) — génère la configuration ESLint de General Translation lors de l’initialisation. * `eslintSeverity` (`'error' | 'warn'`, default `'warn'`) — niveau de sévérité des règles générées. * `overwriteESLintConfig` (`boolean`, default `false`) — permet d’écraser un fichier `eslint.config.mjs` existant. Consultez [le linting de votre code](/docs/react/guides/linting-your-code) pour les règles elles-mêmes. ## Traductions locales ou via CDN [#translations] Par défaut, `gt-next` récupère les traductions depuis le CDN de General Translation à l’exécution — le contenu traduit y est automatiquement mis en ligne lorsque vous exécutez `npx gt translate`. Vous pouvez aussi inclure les traductions dans le bundle de votre application et les charger localement. Les traductions locales se chargent plus rapidement et fonctionnent hors ligne, au prix d’un bundle plus volumineux et d’un redéploiement à chaque modification du contenu. Pour les utiliser, ajoutez un fichier `loadTranslations` qui renvoie les traductions d’un paramètre régional : ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`../public/_gt/${locale}.json`); return translations.default; } ``` `withGTConfig` repère automatiquement un fichier `loadTranslations.[js|ts]` à la racine du projet ou dans le répertoire `src/` (ou définissez explicitement [`loadTranslationsPath`](#load-translations-path)). Faites ensuite pointer la CLI vers ce même répertoire pour que `npx gt translate` y écrive les fichiers. Consultez [Stocker les traductions en local](/docs/react/guides/storing-translations) pour le workflow complet. ## Renvoie [#returns] `withGTConfig` renvoie un objet `NextConfig` enrichi des paramètres de General Translation. Il provoque une erreur au build en cas de conflit de configuration, si une clé API requise est manquante, si un paramètre régional non valide est utilisé avec les services General Translation, ou si une clé de développement est présente en production.