# General Translation React SDKs (gt-react, gt-next): React Quickstart
URL: https://generaltranslation.com/fr/docs/react/react-quickstart.mdx
---
title: React Quickstart
description: Ajoutez plusieurs langues à une app React avec rendu côté serveur grâce à General Translation, en moins de 10 minutes.
related:
links:
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables
---
# React Quickstart
À 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+
**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.
## 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.
```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é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` (étape 3).
### 3. Créez un loader de traduction
Créez une fonction `loadTranslations` 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` :
```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`** à 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 chargeur 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`**, puis passez les deux à **``** :
```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 (
{children}
);
}
```
### 6. Marquer le contenu à traduire
Entourez le texte que vous souhaitez traduire avec le composant **``**. `` signifie "translate" :
```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.
);
}
```
Pour les chaînes de caractères simples — comme les attributs `placeholder` ou les valeurs `aria-label` — utilisez le hook **`useGT`** :
```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';
export default function ContactForm() {
const gt = useGT();
return ;
}
```
### 7. Ajouter un sélecteur de langue
Ajoutez un **``** pour permettre aux utilisateurs de changer de langue :
```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';
export default function Header() {
return ;
}
```
Lorsque l'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'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`.
Obtenez gratuitement vos clés sur [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) ou en exécutant :
```bash
npx gt auth
```
**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.
### 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 && "
}
}
```
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
```
**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`.
C'est tout — votre application est désormais multilingue. 🎉
## Dépannage [#troubleshooting]
`gt-react` stocke la préférence de langue de l’utilisateur dans un cookie appelé `generaltranslation.locale`. Si vous avez déjà fait des tests avec une autre langue, ce cookie peut remplacer votre sélection. Supprimez vos cookies et réessayez.
* [Chrome](https://support.google.com/chrome/answer/95647)
* [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
* [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
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`.
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
Apple
```
`` et `useGT()` prennent tous deux en charge l’option `$context`.
## Next steps
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables