# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuration d’une SPA basé sur esbuild
URL: https://generaltranslation.com/fr/docs/react/guides/spa/configuring-esbuild-spa.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Comment configurer gt-react dans une application React monopage basée sur esbuild.

Configurez l’environnement d’exécution de l’application et intégrez éventuellement les catalogues de traduction générés à votre build esbuild.

Ce guide prépare l’environnement d’exécution de l’application. Marquez séparément le contenu destiné aux utilisateurs pour traduction.

## Configuration d’une SPA React avec esbuild [#setup]

Initialisez `gt-react` avant l’exécution du point d’entrée de l’application.

### 1. Installer gt-react

Installez la dernière version de `gt-react` avec le gestionnaire de paquets privilégié par le dépôt. S’il est déjà installé, passez cette étape.

### 2. Ajoutez un fichier `gt.config.json` à la racine du projet

Ajoutez un fichier `gt.config.json` à la racine du projet. Ce fichier contiendra la configuration du paquet `gt-react`.

Les paramètres régionaux déjà présents dans le projet ou fournis à la tâche de configuration font foi. Préservez les valeurs `locales` et `defaultLocale` existantes. Les valeurs ci-dessous sont fournies à titre d'exemple uniquement. Si le projet ne comporte aucune configuration de paramètres régionaux, ne déduisez pas les paramètres régionaux requis de ces exemples.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"]
}
```

Le champ facultatif [`src`](/docs/cli/reference/config#src) indique les fichiers sources que GT analyse pour y repérer du contenu inline ; s’il est omis, les motifs glob JavaScript et TypeScript suivants sont utilisés par défaut dans `src`, `app`, `pages` et `components` :

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"],
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

### 3. Initialisez la bibliothèque

Initialisez la bibliothèque avec [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) avant que l’application ne s’affiche ou n’importe des modules utilisant des fonctions de traduction définies au niveau du module.

Créez un fichier d’amorçage à côté du fichier d’entrée existant de l’application. Dans cet exemple, le point d’entrée d’origine est `src/main.tsx` et le nouveau fichier d’amorçage est `src/index.ts`. Configurez les `entryPoints` existants d’esbuild pour qu’ils pointent vers le fichier d’amorçage. Préservez tous les autres paramètres de build.

```js title="esbuild.config.mjs"
const buildOptions = {
  // ...les options existantes du projet
  entryPoints: ['src/index.ts'],
};
```

Si le HTML de développement fait directement référence à l’entrée source d’origine, mettez-le également à jour :

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

Initialisez ensuite GT, puis importez dynamiquement l’entrée d’origine une fois l’initialisation terminée. L’application de référence esbuild génère du code ESM et prend en charge await au niveau supérieur :

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

await initializeGTSPA(gtConfig);

await import('./main'); // afficher l'application uniquement une fois que GT est prêt
```

Si la cible de sortie esbuild actuelle ne prend pas en charge top-level await, ne modifiez pas le format de sortie de l’application uniquement pour cette configuration. Utilisez plutôt une fonction d’amorçage async :

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

async function bootstrap() {
  await initializeGTSPA(gtConfig);
  await import('./main');
}

void bootstrap();
```

## Chargement des traductions [#translations]

Lorsque [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) est appelé sans fonction [`loadTranslations`](/docs/react/reference/functions/load-translations), le runtime charge les traductions depuis le CDN de General Translation uniquement si un [`projectId`](/docs/react/reference/config#project-id) est disponible. Pour intégrer les catalogues au bundle de l’application, configurez un chemin de sortie et un loader correspondant. Les étapes ci-dessous utilisent `src/_gt/[locale].json`.

### 1. Mettre à jour la configuration

Définissez `files.gt.output` sur l’emplacement où le CLI doit écrire les fichiers de traduction générés.

Ajoutez ou fusionnez uniquement le paramètre `files.gt.output`. Préservez les `locales` et `defaultLocale` existants du projet ; les valeurs indiquées ci-dessous ne sont que des exemples et ne doivent pas remplacer les paramètres régionaux configurés du projet.

Dans une application basé sur esbuild, les traductions sont généralement stockées dans le répertoire `src/_gt`. Cela permet à esbuild d’inclure les modules de traduction dans le bundle de l’application.

```json title="gt.config.json"
{
  "locales": ["fr", "zh"],
  "defaultLocale": "en",
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

### 2. Ajoutez les fichiers vides

Créez un fichier JSON vide pour chaque paramètre régional cible déjà configuré dans `gt.config.json`, à l’exception du paramètre régional par défaut. Ces fichiers vides permettent aux imports d’être résolus avant que les bundles de traduction n’existent. Les fichiers `fr` et `zh` ci-dessous illustrent la configuration utilisée dans ce guide ; créez plutôt les fichiers correspondant aux paramètres régionaux cibles réellement configurés pour votre projet. Si aucun paramètre régional cible n’est configuré, n’en inventez pas et ne créez pas de fichiers placeholder.

<Files>
  <Folder name="src">
    <Folder name="_gt">
      <File name="fr.json" />

      <File name="zh.json" />
    </Folder>
  </Folder>
</Files>

```json title="src/_gt/fr.json"
{}
```

```json title="src/_gt/zh.json"
{}
```

### 3. Ajouter le loader

Créez `src/loadTranslations.ts` pour charger les traductions. Il doit pointer vers le même emplacement de sortie configuré dans `files.gt.output`.

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

### 4. Mettre à jour l’initialiseur

Mettez à jour l’initialiseur pour utiliser la nouvelle fonction loader. Préservez la forme d’amorçage avec top-level await ou une fonction async utilisée par l’application.

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({ ...gtConfig, loadTranslations });

await import('./main');
```

## Next steps

- /docs/react/guides/spa/internationalizing-react-spa
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/storing-translations
- /docs/react/guides/managing-locales

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.