Welcome to my app

# General Translation React SDKs (gt-react, gt-next, gt-react-native): React Quickstart
URL: https://generaltranslation.com/fr/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Ajoutez plusieurs langues à une application React avec rendu côté serveur grâce à General Translation en moins de 10 minutes.

À la fin de ce guide, votre application React avec rendu côté serveur affichera du contenu en plusieurs langues, avec un sélecteur de langue que vos utilisateurs pourront utiliser.

**Prérequis :**

* Une application React avec rendu côté serveur (React Router ou une configuration SSR personnalisée)
* Node.js 18+

<Callout type="info">
  **Remarque :** Si votre application s’affiche entièrement dans le navigateur avec Vite, suivez plutôt le [React SPA Quickstart](/docs/react/react-spa-quickstart). Il n’utilise pas du tout le provider.
</Callout>

## Quickstart [#quickstart]

### 1. Installez les paquets

`gt-react` est la bibliothèque qui alimente les traductions dans votre application. `gt` est l’outil CLI qui prépare les traductions pour la production.

<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éez un fichier de configuration de traduction

Créez un fichier **`gt.config.json`** à la racine de votre projet. Cela indique à la bibliothèque les langues prises 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 dans 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’importation de votre fonction [`loadTranslations`](/docs/react/reference/functions/load-translations) (étape 3).

### 3. Créez un loader de traduction

Créez une fonction [`loadTranslations`](/docs/react/reference/functions/load-translations) qui charge le fichier de traduction correspondant à un paramètre régional. Sur le serveur, elle s’exécute lors du rendu ; le CLI génère les fichiers lorsque vous lancez [`npx gt translate`](/docs/cli/reference/commands/translate) :

```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) {
    return {};
  }
}
```

### 4. Initialiser la bibliothèque

Appelez **[`initializeGT`](/docs/react/reference/config#initialize)** à la portée du module dans un fichier chargé à la fois côté serveur et côté client — votre route racine ou votre layout est l’endroit idéal. Cette fonction enregistre votre configuration et le loader de traduction une seule fois ; la configuration est immuable pendant toute la durée de vie de l’application :

```tsx title="src/routes/root.tsx"
import { initializeGT } from 'gt-react';
import gtConfig from '../../gt.config.json';
import loadTranslations from '../loadTranslations';

initializeGT({
  defaultLocale: gtConfig.defaultLocale,
  locales: gtConfig.locales,
  loadTranslations,
});
```

### 5. Charger les traductions sur le serveur

Dans le loader de votre route racine (ou le gestionnaire côté serveur équivalent), déterminez le paramètre régional de la requête et récupérez un instantané des traductions avec **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)**, puis passez les deux à **[`<GTProvider>`](/docs/react/reference/components/gt-provider)** :

```tsx title="src/routes/root.tsx"
import {
  GTProvider,
  getTranslationsSnapshot,
  parseLocale,
} from 'gt-react';

// Dans votre loader de route (l'API exacte dépend de votre framework)
export async function loader({ request }) {
  const locale = parseLocale(request); // [!code highlight]
  return {
    locale,
    translations: await getTranslationsSnapshot(locale), // [!code highlight]
  };
}

export default function Root({ children }) {
  const { locale, translations } = useLoaderData();
  return (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```

### 6. Marquer le contenu à traduire

Entourez le texte que vous souhaitez traduire avec le composant **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) signifie &quot;translate&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>
  );
}
```

Pour les chaînes de caractères simples — comme les attributs `placeholder` ou les valeurs `aria-label` — utilisez le hook **[`useGT`](/docs/react/reference/hooks/use-gt)** :

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

export default function ContactForm() {
  const gt = useGT();
  return <input placeholder={gt('Enter your email')} />;
}
```

### 7. Ajouter 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/Header.tsx"
import { LocaleSelector } from 'gt-react';

export default function Header() {
  return <LocaleSelector />;
}
```

Lorsque l&#39;utilisateur choisit une langue, `gt-react` enregistre ce choix dans le cookie `generaltranslation.locale` et recharge la page pour que le serveur réaffiche l&#39;ensemble dans le nouveau paramètre régional.

### 8. Configurer les variables d’environnement (facultatif)

Les traductions de développement à la demande s’exécutent dans le navigateur. Rendez l’ID du projet et la clé API de développement accessibles au code client à l’aide des variables d’environnement publiques de votre framework. N’exposez jamais une clé API de production.

Avec Vite, `gt-react` lit automatiquement ces variables :

```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="your-dev-api-key"
```

Pour les autres frameworks, utilisez leur convention de variables d’environnement côté client et transmettez les valeurs exposées à [`initializeGT`](/docs/react/reference/config#initialize).

Obtenez gratuitement vos clés sur [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) ou en exécutant :

```bash
npx gt auth
```

<Callout type="warn">
  **Avertissement :** Pour le développement, utilisez une clé commençant par `gtx-dev-`. Les clés de production (`gtx-api-`) sont réservées au CI/CD.
</Callout>

### 9. Déployez en production

En production, les traductions sont pré-générées lors du build (sans appels d’API en temps réel). Ajoutez la commande `translate` à votre script de build :

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

Définissez vos variables d’environnement de **production** chez votre hébergeur :

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  **Avertissement :** Les clés de production commencent par `gtx-api-` (et non par `gtx-dev-`). Récupérez-en une sur [dash.generaltranslation.com](https://dash.generaltranslation.com). N’exposez jamais publiquement votre `GT_API_KEY`.
</Callout>

C&#39;est tout — votre application est désormais multilingue. 🎉

## 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 le sélecteur s’affiche sous [`<GTProvider>`](/docs/react/reference/components/gt-provider). Si vous fournissez un callback [`_reload`](/docs/react/reference/components/gt-provider#reload) personnalisé, vérifiez qu’il recharge la page ou déclenche une navigation après la sélection.
  </Accordion>

  <Accordion title="Les traductions sont lentes en développement">
    C’est normal. En développement, les traductions se font à la demande (votre contenu est traduit en temps réel via l’API). Ce délai **n’existe pas en production** — toutes les traductions sont pré-générées par [`npx gt translate`](/docs/cli/reference/commands/translate).
  </Accordion>

  <Accordion title="Certaines traductions sont inexactes">
    Un texte ambigu peut entraîner des traductions inexactes. Par exemple, &quot;apple&quot; 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/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

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