# General Translation React SDKs (gt-react, gt-next, gt-react-native): React SPA Démarrage rapide
URL: https://generaltranslation.com/fr/docs/react/react-spa-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Ajoutez plusieurs langues à une application React monopage.
À la fin de ce guide, votre application React monopage affichera du contenu en plusieurs langues, avec un sélecteur de langue que vos utilisateurs pourront utiliser.
Dans une application monopage, `gt-react` s’exécute entièrement dans le navigateur — vous l’initialisez une seule fois au démarrage avec [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa), et vous n’avez pas besoin d’un composant provider.
**Prérequis :**
* Une application React avec rendu côté client (Vite, webpack ou similaire)
* Node.js 18+
Votre système de build peut nécessiter une version plus récente de Node.js. Par exemple, Vite 8 requiert `^20.19.0 || >=22.12.0`.
**Astuce :** Exécutez `npx gt@latest` pour configurer l’amorçage de Vite et le chargement des traductions avec l’[assistant de configuration](/docs/cli/quickstart). Ce guide présente la configuration manuelle.
**Remarque :** Si votre application effectue un rendu côté serveur, suivez plutôt le [React Démarrage rapide](/docs/react/react-quickstart).
## Choisissez votre bundler [#bundlers]
Les étapes ci-dessous utilisent Vite comme exemple principal. Pour un autre système de build, consultez
son guide de configuration pour le point d’entrée, l’amorçage et le loader de traduction :
Configurez le point d’entrée HTML de Vite et le chargement des traductions.
Configurez le point d’entrée webpack et le contexte de traduction.
Configurez les points d’entrée esbuild et les contenus de secours selon la cible de sortie.
Configurez l’entrée Rollup et une carte des paramètres régionaux analysable statiquement.
Configurez l’entrée Rolldown et une carte des paramètres régionaux analysable statiquement.
Déclarez l’amorçage, la configuration, le paquet et les traductions comme entrées Bazel.
Après la configuration, consultez [Internationaliser une SPA React](/docs/react/guides/spa/internationalizing-react-spa)
pour des recommandations spécifiques aux SPA concernant JSX, les chaînes, la sélection du paramètre régional et la validation.
## Démarrage rapide [#quickstart]
### 1. Installez les paquets
`gt-react` est la bibliothèque qui gère les traductions dans votre application. `gt` est l’outil CLI qui prépare vos traductions.
```bash
npm i gt-react
npm i -D gt
```
```bash
yarn add gt-react
yarn add --dev gt
```
```bash
bun add gt-react
bun add --dev gt
```
```bash
pnpm add gt-react
pnpm add --save-dev gt
```
### 2. Créer un fichier de configuration de traduction
Créez un fichier **`gt.config.json`** à la racine de votre projet. Ce fichier indique à la bibliothèque les langues que vous prenez en charge :
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "fr", "ja"],
"files": {
"gt": {
"output": "src/_gt/[locale].json"
}
}
}
```
* **`defaultLocale`** — la langue dans laquelle votre application est écrite (votre langue source).
* **`locales`** — les langues vers lesquelles vous souhaitez traduire. Choisissez-les dans la [liste des paramètres régionaux pris en charge](/docs/platform/dashboard/reference/supported-locales).
* **`files`** — indique au CLI où enregistrer les fichiers de traduction. Le chemin `output` doit correspondre au chemin d’import de votre fonction [`loadTranslations`](/docs/react/reference/functions/load-translations) (étape 3).
Par défaut, le CLI analyse les fichiers JavaScript et TypeScript situés dans `src`, `app`, `pages` et `components`. Définissez [`src`](/docs/cli/reference/config#src) si votre source se trouve ailleurs.
**Remarque :** Les bundlers comme Vite importent les fichiers de traduction sous forme de modules. Les fichiers de traduction doivent donc se trouver dans `src/`.
### 3. Créer un loader de traduction
Dans une SPA, `gt-react` a besoin d’une fonction pour charger les fichiers de traduction dans le navigateur à l’exécution. Créez un fichier [`loadTranslations`](/docs/react/reference/functions/load-translations) :
```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
try {
const translations = await import(`./_gt/${locale}.json`);
return translations.default;
} catch (error) {
console.warn(`No translations found for ${locale}`);
return {};
}
}
```
Cette fonction charge les fichiers de traduction JSON à partir de votre répertoire `src/_gt/`. Le CLI génère ces fichiers lorsque vous exécutez [`npx gt translate`](/docs/cli/reference/commands/translate).
**Rollup :** Rollup seul ne peut pas analyser l’importation entièrement dynamique ci-dessus. Utilisez plutôt le [mappage statique des loaders de paramètres régionaux](/docs/react/guides/developing-spa-translations#setup).
Create React App peut utiliser le loader du répertoire source ci-dessus. Si vous préférez conserver les traductions générées dans `public/`, modifiez le chemin de sortie du CLI en `public/_gt/[locale].json` :
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "fr", "ja"],
"files": {
"gt": {
"output": "public/_gt/[locale].json"
}
}
}
```
Chargez le fichier via HTTP avec `PUBLIC_URL` :
```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
try {
const response = await fetch(
`${process.env.PUBLIC_URL}/_gt/${locale}.json`
);
if (!response.ok) throw new Error('Translation file not found');
return await response.json();
} catch {
console.warn(`No translations found for ${locale}`);
return {};
}
}
```
### 4. Initialiser la bibliothèque
Appelez **[`initializeGTSPA`](/docs/react/reference/config#initialize-spa)** une seule fois au démarrage, avant le rendu de votre application. Cette fonction prend votre configuration et votre loader de traduction, détermine le paramètre régional de l'utilisateur et charge les traductions correspondantes.
L'approche la plus robuste consiste à utiliser un petit module d'entrée qui initialise d'abord GT, puis charge le reste de l'application. Cela vous permet de traduire le contenu au niveau du module.
```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'); // rendre l'application uniquement une fois que GT est prêt
```
CommonJS ne prend pas en charge `await` au niveau supérieur. Encapsulez l’initialisation dans une fonction de démarrage asynchrone, puis importez dynamiquement l’application. Cela préserve le contexte asynchrone requis pour les appels [`t()`](/docs/react/reference/functions/t-function) au niveau du module.
```js title="src/index.js"
const { initializeGTSPA } = require('gt-react');
const gtConfig = require('../gt.config.json');
async function loadTranslations(locale) {
try {
return require(`./_gt/${locale}.json`);
} catch (error) {
console.warn(`No translations found for ${locale}`);
return {};
}
}
async function start() {
await initializeGTSPA({
...gtConfig,
loadTranslations,
});
await import('./main');
}
start().catch(console.error);
```
**Avertissement :** N’appelez pas `require` sur `main` avant l’initialisation. Cela évalue les appels [`t()`](/docs/react/reference/functions/t-function) au niveau du module avant que les traductions ne soient prêtes.
```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')!).render(
);
```
Mettez ensuite à jour la balise de script de type module dans votre `index.html` pour qu’elle pointe vers la nouvelle entrée : remplacez son `src` de `/src/main.tsx` par `/src/index.ts`.
```html title="index.html"
```
[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) s’exécute une seule fois au démarrage — la configuration est immuable pendant toute la durée de vie de l’application. Une fois l’initialisation terminée, les traductions peuvent être récupérées dans n’importe quel module. **Vous n'avez pas besoin d'entourer votre application d’un provider.**
Create React App bloque les importations depuis l’extérieur de `src/` et ne prend pas en charge `await` au niveau supérieur. Conservez le fichier `gt.config.json` à la racine pour la CLI, renommez votre point d’entrée `src/index.tsx` existant en `src/main.tsx`, puis créez ce nouveau point d’entrée :
```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import loadTranslations from './loadTranslations';
async function start() {
await initializeGTSPA({
defaultLocale: 'en',
locales: ['es', 'fr', 'ja'],
loadTranslations,
});
await import('./main');
}
start().catch(console.error);
```
Gardez ces valeurs de paramètres régionaux synchronisées avec la configuration à la racine chaque fois que vous ajoutez ou supprimez une langue. Ne modifiez pas `public/index.html` ; Create React App charge déjà `src/index`.
**Astuce :** Suivez [Développer avec les traductions SPA](/docs/react/guides/developing-spa-translations) pour ajouter le compiler et les identifiants de développement.
### 5. Marquer le contenu à traduire
Maintenant, entourez tout texte que vous souhaitez traduire avec le composant **[``](/docs/react/reference/components/t)**. [``](/docs/react/reference/components/t) signifie "traduire" :
```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';
export default function Welcome() {
return (
Welcome to my app
This content will be translated automatically.
);
}
```
Vous pouvez entourer autant ou aussi peu de JSX que vous le souhaitez avec [``](/docs/react/reference/components/t). Tout ce qu’il contient — texte, éléments imbriqués, même la mise en forme — est traduit comme un tout.
Pour les chaînes en dehors des composants React, utilisez **[`t()`](/docs/react/reference/functions/t-function)**. Cela fonctionne au niveau du module, car [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) charge les traductions avant le reste de votre application :
```ts title="src/navigation.ts"
import { t } from 'gt-react';
export const navigation = [
{ label: t('Home'), href: '/' },
{ label: t('About'), href: '/about' },
];
```
### 6. Ajoutez un sélecteur de langue
Ajoutez un **[``](/docs/react/reference/components/locale-selector)** pour permettre aux utilisateurs de changer de langue :
```tsx title="src/components/Welcome.tsx"
import { T, LocaleSelector } from 'gt-react';
export default function Welcome() {
return (