# General Translation Knowledge Base: Comment migrer de react-i18next vers gt-react ?
URL: https://generaltranslation.com/fr/kb/migrate-from-react-i18next.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Installez gt-react aux côtés de react-i18next, partagez un même cookie de paramètre régional et migrez un composant à la fois, en remplaçant les clés t() et `<Trans>` par du texte intégré dans `<T>` et useGT. General Translation traduit le texte migré en s’appuyant sur son JSX comme contexte, et votre équipe peut le corriger dans le tableau de bord. Les composants non migrés conservent leurs traductions react-i18next déjà relues.
Category: Internationalisation
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

react-i18next affiche les traductions que vous rédigez dans un fichier JSON par langue et par espace de noms. gt-react affiche le texte écrit directement dans vos composants, et General Translation génère les traductions avec [`npx gt translate`](/docs/cli/reference/commands/translate). Une migration consiste à remplacer chaque recherche `t('key')` par le texte source auquel elle renvoie, un composant à la fois, tandis que les deux bibliothèques cohabitent.

Il n’est pas nécessaire de migrer pour utiliser General Translation. La CLI `gt` détecte `i18next` dans votre `package.json` et traduit ses fichiers JSON en conservant intacte la syntaxe `{{variable}}` d’i18next. Migrez si vous souhaitez placer le texte à côté du JSX qui l’affiche, sans avoir à nommer des clés ni à synchroniser manuellement des fichiers par langue.

## Quelles sont les équivalences entre les API de react-i18next et gt-react ?

| react-i18next                                  | gt-react                                                                                                                                                                                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `i18n.init({ lng, supportedLngs, resources })` | `gt.config.json` (`defaultLocale`, `locales`) et [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) dans le fichier d’entrée                                                                                     |
| `I18nextProvider` / `initReactI18next`         | Aucun fournisseur dans une application monopage (SPA) ; les applications server-rendered utilisent [`initializeGT`](/docs/react/reference/config#initialize) avec [`GTProvider`](/docs/react/reference/components/gt-provider) |
| `<Trans i18nKey="..." components={...}>`       | [`<T>`](/docs/react/reference/components/t) encapsulant directement le JSX réel, avec les liens et le balisage intégrés                                                                                                        |
| `t('key')` pour les chaînes                    | [`useGT`](/docs/react/reference/hooks/use-gt) avec la chaîne source, ou [`useTranslations`](/docs/react/reference/hooks/use-translations) pour conserver les clés                                                              |
| Interpolation `{{name}}`                       | [`<Var>`](/docs/react/reference/components/var) en JSX ; `{name}` dans les chaînes                                                                                                                                             |
| `key_one` / `key_other` avec `count`           | [`<Plural>`](/docs/react/reference/components/plural) en JSX ; ICU `{n, plural, ...}` dans les chaînes                                                                                                                         |
| `useTranslation('ns')` ou `keyPrefix`          | `useTranslations('ns')` limite les recherches à un préfixe                                                                                                                                                                     |
| `{{val, number}}` et autres formateurs         | [`<Num>`](/docs/react/reference/components/num), [`<Currency>`](/docs/react/reference/components/currency) et [`<DateTime>`](/docs/react/reference/components/datetime)                                                        |
| `i18n.changeLanguage()` / `i18n.language`      | [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) / [`useLocale`](/docs/react/reference/hooks/use-locale), ou le composant [`<LocaleSelector>`](/docs/react/reference/components/locale-selector)                   |
| `i18next-browser-languagedetector`             | Intégré : le cookie `generaltranslation.locale`, puis les langues du navigateur                                                                                                                                                |
| `fallbackLng`                                  | En l’absence de traduction, le texte source est affiché                                                                                                                                                                        |

## Étape 1 : installer gt-react en parallèle de react-i18next

Suivez le [Démarrage rapide pour une SPA React](/docs/react/react-spa-quickstart) pour une application Vite ou webpack, ou le [Démarrage rapide avec React](/docs/react/react-quickstart) pour une application server-rendered. Dans une SPA, la configuration initiale se déroule ainsi :

1. Installez `gt-react`, ainsi que la CLI `gt` en tant que dépendance de développement.
2. Créez `gt.config.json` avec le même paramètre régional source et les mêmes paramètres régionaux cibles que dans votre configuration i18next.
3. Ajoutez une fonction [`loadTranslations`](/docs/react/reference/functions/load-translations), puis appelez [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) dans un fichier d’entrée qui n’importe le reste de l’application qu’une fois les traductions chargées.
4. Connectez-vous avec [`npx gt login`](/docs/cli/reference/commands/login) et définissez votre identifiant de projet.

Conservez `i18n.init` et vos fichiers JSON tels quels. Rien ne change pour les utilisateurs tant que vous n’avez pas migré de composant. Si `gt.config.json` répertorie vos fichiers i18next sous `files`, supprimez cette entrée afin que chaque chaîne de caractères ne dépende que d’une seule source de traduction : les fichiers JSON conservent leurs traductions pour les composants non migrés, tandis que les textes nouveaux ou modifiés sont intégrés directement dans gt-react.

## Étape 2 : conserver une seule locale active

Deux bibliothèques peuvent ne pas s&#39;accorder sur la langue de l&#39;utilisateur. Utilisez gt-react comme sélecteur de langue et faites en sorte qu&#39;i18next lise le même cookie :

```ts title="src/i18n.ts"
import i18n from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import { initReactI18next } from 'react-i18next';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    // ...vos options existantes
    detection: {
      order: ['cookie', 'navigator'],
      lookupCookie: 'generaltranslation.locale', // le cookie écrit par gt-react
      caches: [],
    },
  });
```

Remplacez votre ancien menu de langues par le composant [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) de gt-react, ou par un contrôle qui appelle [`useSetLocale`](/docs/react/reference/hooks/use-set-locale). Dans une SPA, changer de langue enregistre le cookie et recharge la page : les deux bibliothèques démarrent ainsi dans la nouvelle langue. Testez la navigation entre les écrans migrés et non migrés avant de passer à la suite.

## Étape 3 : migrer un composant à la fois

Copiez le texte en langue source depuis votre fichier JSON dans le composant, en conservant les variables sous forme de variables. Avant :

```json title="public/locales/en/translation.json"
{
  "inbox": "Hi {{name}}, <link>open your inbox</link>.",
  "messages_one": "You have {{count}} message",
  "messages_other": "You have {{count}} messages"
}
```

```tsx title="src/Inbox.tsx"
import { Trans, useTranslation } from 'react-i18next';

export function Inbox({ name, count }: { name: string; count: number }) {
  const { t } = useTranslation();
  return (
    <>
      <Trans i18nKey="inbox" values={{ name }} components={{ link: <a href="/inbox" /> }} />
      <p>{t('messages', { count })}</p>
    </>
  );
}
```

Après :

```tsx title="src/Inbox.tsx"
import { T, Var, Plural, Num } from 'gt-react';

export function Inbox({ name, count }: { name: string; count: number }) {
  return (
    <T>
      Hi <Var>{name}</Var>, <a href="/inbox">open your inbox</a>.
      <p>
        <Plural
          n={count}
          singular={<>You have <Num>{count}</Num> message</>}
          plural={<>You have <Num>{count}</Num> messages</>}
        />
      </p>
    </T>
  );
}
```

Le lien reste un véritable élément `<a>` au lieu d&#39;être remplacé par un espace réservé numéroté. General Translation traduit l&#39;ensemble du bloc en s&#39;appuyant sur sa structure comme contexte et, à partir des formes `singular` et `plural` que vous rédigez, génère les formes requises par chaque langue cible, comme les formes `few` et `many` du polonais. [`<Plural>`](/docs/react/reference/components/plural) sélectionne ensuite la forme appropriée pour chaque quantité.

Pour les chaînes situées hors du JSX, comme les textes d&#39;espace réservé et les notifications toast, utilisez [`useGT`](/docs/react/reference/hooks/use-gt). Les variables s&#39;écrivent entre accolades simples, et vous pouvez ajouter du contexte pour lever l&#39;ambiguïté de certains mots :

```tsx
import { useGT } from 'gt-react';

function Search({ count }: { count: number }) {
  const gt = useGT();
  return <input placeholder={gt('Search {count} projects', { count })} />;
}

// Dans un gestionnaire d’événements, avec une indication pour le traducteur :
toast(gt('Saved {fileName}', { fileName, $context: 'toast after saving a file' }));
```

Le premier argument doit être une chaîne de caractères statique, et non un littéral de gabarit ou une concaténation. Après chaque lot de composants, exécutez [`npx gt translate`](/docs/cli/reference/commands/translate) et vérifiez tous les paramètres régionaux.

## Pouvez-vous conserver vos clés de traduction ?

Oui. Regroupez vos clés dans un seul [dictionnaire](/docs/react/guides/translating-with-dictionaries) gt-react et remplacez `useTranslation` par [`useTranslations`](/docs/react/reference/hooks/use-translations). L&#39;appel de recherche ne change pas :

```tsx
// Avant
import { useTranslation } from 'react-i18next';
const { t } = useTranslation();

// Après
import { useTranslations } from 'gt-react';
const t = useTranslations();

return <h1>{t('home.welcome', { name })}</h1>;
```

Les entrées de dictionnaire utilisent ICU MessageFormat ; le JSON nécessite donc trois modifications :

* `{{name}}` devient `{name}`.
* Les clés de pluriel sont fusionnées en une seule entrée : `"messages": "You have {count, plural, one {# message} other {# messages}}"`.
* Les fichiers d’espace de noms sont fusionnés en un seul `dictionary.json`, où chaque espace de noms devient une clé de premier niveau. `useTranslation('settings')` devient `useTranslations('settings')`.

[`npx gt validate`](/docs/cli/reference/commands/validate) signale les entrées dont la syntaxe ICU n&#39;est pas valide. Contrairement à i18next, qui renvoie la clé lorsqu&#39;une entrée est manquante, [`useTranslations`](/docs/react/reference/hooks/use-translations) lève une exception : veillez donc à maintenir les id et les entrées synchronisés.

## Qu&#39;advient-il de vos traductions existantes ?

Les composants que vous n&#39;avez pas migrés continuent d&#39;afficher leurs traductions react-i18next déjà relues : une migration progressive ne modifie donc que les écrans sur lesquels vous intervenez. Les textes que vous déplacez dans [`<T>`](/docs/react/reference/components/t), [`useGT`](/docs/react/reference/hooks/use-gt) ou un dictionnaire gt-react reçoivent de nouvelles traductions générées par [`npx gt translate`](/docs/cli/reference/commands/translate), qui tiennent compte de la structure JSX de [`<T>`](/docs/react/reference/components/t) et du contexte que vous ajoutez. Le glossaire et les instructions personnalisées d&#39;un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) garantissent la cohérence de votre terminologie et de votre ton. Les relecteurs peuvent ensuite ajuster n&#39;importe quelle formulation dans le [tableau de bord](/docs/platform/dashboard/guides/reviewing-translations).

Si chaque traduction relue doit rester strictement identique, conservez react-i18next et confiez plutôt à General Translation la traduction de ses fichiers JSON. (Voir [General Translation vs. i18next](/kb/general-translation-vs-i18next).)

## Étape 4 : supprimer react-i18next

Lorsqu&#39;une recherche de `useTranslation`, `<Trans` et `i18next` ne renvoie plus aucun résultat, supprimez le fichier `i18n.init`, les fichiers JSON, le détecteur de langue ainsi que les dépendances `i18next` et `react-i18next`. Ajoutez ensuite [`npx gt translate`](/docs/cli/reference/commands/translate) à votre processus de compilation ou à votre [CI](/kb/translations-in-ci) pour que les nouveaux textes soient livrés traduits à chaque livraison.

## Questions fréquentes

### Dois-je tout migrer d&#39;un coup ?

Non. Les deux bibliothèques peuvent afficher du contenu sur la même page, à condition de lire le même paramètre régional. Migrez une route ou une fonctionnalité à la fois, puis supprimez i18next une fois que plus rien ne l&#39;utilise.

### gt-react prend-il en charge le rendu côté serveur ?

Oui. Les applications React avec rendu côté serveur utilisent [`initializeGT`](/docs/react/reference/config#initialize) avec [`GTProvider`](/docs/react/reference/components/gt-provider) au lieu de [`initializeGTSPA`](/docs/react/reference/config#initialize-spa). Consultez le guide [Démarrage rapide avec React](/docs/react/react-quickstart), ou le guide [Démarrage rapide avec Next.js](/docs/react/nextjs-quickstart) si vous utilisez `gt-next`.

### gt-react est-il gratuit ?

gt-react est distribué sous licence MIT et affiche les traductions incluses dans le bundle sans qu&#39;aucun compte soit nécessaire. La génération de traductions avec General Translation est [facturée à l&#39;usage](https://generaltranslation.com/pricing).

## Points clés

* Exécutez gt-react en parallèle de react-i18next, configurez le détecteur de langue d&#39;i18next pour qu&#39;il lise le cookie `generaltranslation.locale`, et changez de langue avec gt-react.
* Remplacez `<Trans>` et les recherches par clé par du texte intégré dans [`<T>`](/docs/react/reference/components/t) et [`useGT`](/docs/react/reference/hooks/use-gt) ; `{{var}}` devient [`<Var>`](/docs/react/reference/components/var) ou `{var}`, et les clés de pluriel deviennent [`<Plural>`](/docs/react/reference/components/plural) avec `singular` et `plural`.
* Les composants non migrés conservent leurs traductions relues ; le texte migré est traduit avec son JSX comme contexte, puis relu dans le tableau de bord.
* Pour conserver les clés, convertissez votre JSON en un dictionnaire ICU unique et utilisez [`useTranslations`](/docs/react/reference/hooks/use-translations).
* Ne supprimez i18next qu&#39;une fois que plus rien ne le lit, puis exécutez [`npx gt translate`](/docs/cli/reference/commands/translate) dans votre CI.

## Related questions

- [Alternatives à i18next : General Translation ou i18next](https://generaltranslation.com/fr/kb/general-translation-vs-i18next.mdx): Choisissez General Translation pour conserver vos textes directement dans vos composants React et générer des traductions en tirant parti de leur structure JSX et du contexte de votre produit. Vous pouvez aussi conserver i18next et utiliser General Translation pour traduire vos catalogues existants. i18next assure le rendu des messages et la sélection des formes plurielles ; la génération des traductions relève d’un service distinct.
- [Comment traduire une application React ?](https://generaltranslation.com/fr/kb/translate-react-app.mdx): Traduire une application React consiste à internationaliser ses composants pour qu’ils s’affichent dans la langue de l’utilisateur, puis à traduire chaque chaîne de caractères dans chacune des langues prises en charge. gt-react de General Translation traduit le JSX sur place dans le composant `<T>`, et npx gt translate génère un fichier par langue.
- [Comment traduire des chaînes en dehors du JSX ?](https://generaltranslation.com/fr/kb/translate-strings-outside-jsx.mdx): Faites passer chaque chaîne qui n’est pas un enfant JSX, comme un espace réservé ou une constante définie au niveau du module, par une fonction de traduction à l’endroit où elle est affichée. Le hook useGT de General Translation renvoie cette fonction, et msg, combiné à useMessages, traduit les constantes définies en dehors d’un composant.
- [Comment gérer les formes plurielles dans React ?](https://generaltranslation.com/fr/kb/how-to-handle-plurals-in-react.mdx): Pour gérer les formes plurielles dans React, fournissez à chaque langue une phrase par forme du pluriel et sélectionnez-la selon les règles de pluriel de cette langue, car l’anglais compte 2 formes, le russe 4 et l’arabe 6. Le composant `<Plural>` de General Translation, disponible dans gt-react et gt-next, prend vos formes source, et General Translation génère les formes requises par chaque langue cible.
- [Comment maintenir les traductions à jour à chaque déploiement ?](https://generaltranslation.com/fr/kb/translations-in-ci.mdx): Exécutez la traduction comme une étape du pipeline avant chaque compilation de production, afin que les nouveaux textes soient livrés traduits avec le déploiement qui les ajoute. Le CLI gt de General Translation s’en charge avec npx gt translate, à l’aide d’une clé API de projet et d’un identifiant de projet stockés comme secrets CI.

## Previous and next questions

- Previous question: [Comment migrer de next-intl vers gt-next ?](https://generaltranslation.com/fr/kb/migrate-from-next-intl.mdx)
- Next question: [Comment migrer de vue-i18n vers gt-vue ?](https://generaltranslation.com/fr/kb/migrate-from-vue-i18n.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.