# 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`.

<Callout type="info">
  **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.
</Callout>

<Callout type="info">
  **Remarque :** Si votre application effectue un rendu côté serveur, suivez plutôt le [React Démarrage rapide](/docs/react/react-quickstart).
</Callout>

## 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 :

<Cards>
  <Card title="Vite" href="/docs/react/guides/spa/configuring-vite-spa">
    Configurez le point d’entrée HTML de Vite et le chargement des traductions.
  </Card>

  <Card title="webpack" href="/docs/react/guides/spa/configuring-webpack-spa">
    Configurez le point d’entrée webpack et le contexte de traduction.
  </Card>

  <Card title="esbuild" href="/docs/react/guides/spa/configuring-esbuild-spa">
    Configurez les points d’entrée esbuild et les contenus de secours selon la cible de sortie.
  </Card>

  <Card title="Rollup" href="/docs/react/guides/spa/configuring-rollup-spa">
    Configurez l’entrée Rollup et une carte des paramètres régionaux analysable statiquement.
  </Card>

  <Card title="Rolldown" href="/docs/react/guides/spa/configuring-rolldown-spa">
    Configurez l’entrée Rolldown et une carte des paramètres régionaux analysable statiquement.
  </Card>

  <Card title="Bazel" href="/docs/react/guides/spa/configuring-bazel-spa">
    Déclarez l’amorçage, la configuration, le paquet et les traductions comme entrées Bazel.
  </Card>
</Cards>

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.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 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.

<Callout type="info">
  **Remarque :** Les bundlers comme Vite importent les fichiers de traduction sous forme de modules. Les fichiers de traduction doivent donc se trouver dans `src/`.
</Callout>

### 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).

<Callout type="info">
  **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).
</Callout>

<Accordions>
  <Accordion title="Conserver les traductions de Create React App dans public ?">
    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 {};
      }
    }
    ```
  </Accordion>
</Accordions>

### 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&#39;utilisateur et charge les traductions correspondantes.

L&#39;approche la plus robuste consiste à utiliser un petit module d&#39;entrée qui initialise d&#39;abord GT, puis charge le reste de l&#39;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
```

<Accordions>
  <Accordion title="Vous utilisez CommonJS ?">
    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);
    ```

    <Callout type="warn">
      **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.
    </Callout>
  </Accordion>
</Accordions>

```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);
```

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"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

[`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&#39;avez pas besoin d&#39;entourer votre application d’un provider.**

<Accordions>
  <Accordion title="Vous utilisez Create React App ?">
    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`.
  </Accordion>
</Accordions>

<Callout type="info">
  **Astuce :** Suivez [Développer avec les traductions SPA](/docs/react/guides/developing-spa-translations) pour ajouter le compiler et les identifiants de développement.
</Callout>

### 5. Marquer le contenu à traduire

Maintenant, entourez tout texte que vous souhaitez traduire avec le composant **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) signifie &quot;traduire&quot; :

```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

Vous pouvez entourer autant ou aussi peu de JSX que vous le souhaitez avec [`<T>`](/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 **[`<LocaleSelector>`](/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 (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`LocaleSelector`](/docs/react/reference/components/locale-selector) affiche un menu déroulant contenant les langues de votre `gt.config.json`.

Lorsque l’utilisateur choisit une langue, `gt-react` enregistre ce choix dans le cookie `generaltranslation.locale` et recharge la page — [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) s’exécute alors à nouveau et charge les traductions du nouveau paramètre régional avant le rendu de l’application.

### 7. Authentifiez-vous et traduisez

Avant de traduire, authentifiez-vous auprès de General Translation :

```bash
npx gt auth
```

Suivez les instructions pour créer un compte ou vous connecter. Lorsque le type de clé vous est demandé, choisissez une clé de production. La commande génère une clé API et un identifiant de projet, puis les ajoute à `.env.local` à la racine de votre projet :

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="gtx-api-your-production-key"
```

<Callout type="warn">
  **Avertissement :** Ne versionnez pas `.env.local` et n’exposez pas `GT_API_KEY` dans le code côté navigateur.
</Callout>

Exécutez ensuite la commande translate pour générer des fichiers de traduction pour chaque paramètre régional configuré :

```bash
npx gt translate
```

Le CLI analyse votre application, en traduit le contenu et écrit les résultats dans le chemin de sortie défini dans `gt.config.json`. Relancez-le chaque fois que votre contenu source est modifié.

### 8. Exécuter et vérifier

Affichez le composant d&#39;exemple depuis votre application :

```tsx title="src/App.tsx"
import Welcome from './components/Welcome';

export default function App() {
  return <Welcome />;
}
```

Démarrez le serveur de développement de votre application (par exemple, `npm run dev` avec Vite), ouvrez son URL locale et sélectionnez `es`, `fr` ou `ja`. Vérifiez que la page se recharge et que le titre affiche bien la traduction sélectionnée.

## Dépannage [#troubleshooting]

<Accordions>
  <Accordion title="La langue ne change pas lorsque j’utilise le menu déroulant">
    Vérifiez que les cookies du navigateur sont activés, que le paramètre régional sélectionné figure dans `gt.config.json` et que [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) soit résolu avant le chargement du module d’entrée de l’application.
  </Accordion>

  <Accordion title="Certaines traductions sont inexactes">
    Un texte ambigu peut entraîner des traductions inexactes. Par exemple, « apple » peut désigner le fruit ou l’entreprise. Ajoutez une prop `$context` pour préciser le sens :

    ```jsx
    <T $context="the technology company">Apple</T>
    ```

    [`<T>`](/docs/react/reference/components/t) et [`useGT()`](/docs/react/reference/hooks/use-gt) prennent tous deux en charge l’option `$context`.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/developing-spa-translations
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

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