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

Configurez le runtime de l’application et, éventuellement, incluez les catalogues de traduction générés dans votre build Rolldown.

Ce guide prépare le runtime de l’application. Marquez séparément le contenu destiné aux utilisateurs à traduire.

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

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

### 1. Installez gt-react

Installez la dernière version de `gt-react` avec le gestionnaire de paquets privilégié du dépôt. Ignorez cette étape s'il est déjà installé.

### 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 existantes de `locales` et `defaultLocale`. 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 à partir de ces exemples.

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

Le champ [`src`](/docs/cli/reference/config#src) facultatif indique les fichiers sources que GT analyse pour rechercher 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 soit affichée 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 fichier d’entrée d’origine est `src/main.tsx` et le nouveau fichier d’amorçage est `src/index.ts`. Configurez l’option `input` existante de Rolldown pour qu’elle pointe vers le fichier d’amorçage. Conservez tous les autres paramètres de build.

```js title="rolldown.config.mjs"
export default {
  // ...les options existantes du projet
  input: 'src/index.ts',
};
```

Si le code 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 uniquement une fois l’initialisation terminée. L’application de référence Rolldown génère des modules 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'); // n'afficher l'application qu'une fois que GT est prêt
```

Si le format de sortie ou la cible Rolldown existante ne prend pas en charge `await au niveau supérieur`, ne le modifiez pas 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 le `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ée sur Rolldown, les traductions sont généralement stockées dans le répertoire `src/_gt`. Rolldown peut ainsi 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 de résoudre les imports avant que les bundles de traduction n’existent. Les fichiers `fr` et `zh` ci-dessous illustrent la configuration d’exemple de ce guide ; créez plutôt des fichiers correspondant aux paramètres régionaux cibles réellement configurés pour le 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. Ajoutez le loader

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

Indiquez explicitement chaque paramètre régional cible configuré dans `translationLoaders`. Chaque loader doit utiliser un chemin d’import littéral afin que Rolldown puisse détecter et générer chaque fichier de traduction au build. Les entrées `fr` et `zh` ci-dessous correspondent à l’exemple de configuration de ce guide ; utilisez plutôt les paramètres régionaux cibles réellement configurés dans le projet.

```ts title="src/loadTranslations.ts"
const translationLoaders = {
  fr: () => import('./_gt/fr.json'),
  zh: () => import('./_gt/zh.json'),
};

export default async function loadTranslations(locale: string) {
  try {
    const loader =
      translationLoaders[locale as keyof typeof translationLoaders];
    if (!loader) {
      console.warn(`No translations found for locale "${locale}"`);
      return {};
    }
    const translations = await loader();
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for locale "${locale}"`, error);
    return {};
  }
}
```

### 4. Mettre à jour l’initialiseur

Mettez à jour l’initialiseur pour utiliser la nouvelle fonction loader. Préservez la forme d’amorçage avec attente au niveau supérieur ou fonction asynchrone 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.