Migrer de react-i18next / i18next à Intlayer

Pourquoi migrer de react-i18next / i18next à Intlayer ?

Stratégies de migration

Il existe deux stratégies complémentaires pour migrer de react-i18next / i18next à Intlayer :

1. Adaptateur de compatibilité (recommandé pour les applications existantes) — Installez @intlayer/react-i18next (pour les composants React) et/or @intlayer/i18next (pour l'instance de base i18n). Ces packages exposent exactement la même API que react-i18next / i18next mais délèguent tout le travail de traduction à Intlayer. Vous conservez vos appels existants à useTranslation, Trans, withTranslation, i18next.t() — le seul changement est le chemin d'importation.

2. Migration complète — Remplacez progressivement les API react-i18next par des hooks natifs Intlayer (useIntlayer, IntlayerProvider) et colocalisez le contenu dans des fichiers .content.ts avec vos composants.

Ce guide couvre d'abord la Stratégie 1 (adaptateur de compatibilité prêt à l'emploi), puis passe en revue la migration complète optionnelle.

Table des Matières

Migration rapide

Les étapes suivantes sont le minimum requis pour faire fonctionner votre application react-i18next existante sur Intlayer avec zéro changement de code.

1. 1

   Installer les Dépendances

   Installez les packages principaux d'Intlayer et les adaptateurs de compatibilité :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Vous pouvez garder react-i18next et i18next installés — les adaptateurs de compatibilité les utilisent comme devDependencies / peerDependencies optionnels pour les types TypeScript. Vous n'avez pas besoin de changer de peers dans package.json.

2. 2

   Configurer Intlayer

   La commande intlayer init crée un fichier intlayer.config.ts de démarrage. Mettez-le à jour pour qu'il corresponde à vos paramètres régionaux existants et pointez le plugin syncJSON sur vos fichiers de messages :

   intlayer.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Ajoutez tous vos paramètres régionaux existants ici
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // correspond à la syntaxe d'espace réservé react-i18next : {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source mappe un paramètre régional à son chemin de fichier JSON. location indique à l'observateur Intlayer quel dossier surveiller pour les modifications. L'option format: 'i18next' garantit que les espaces réservés comme {{name}} sont analysés correctement.

3. 3

   Ajouter le Plugin Intlayer à votre Bundler

   Enveloppez votre configuration de bundler existante avec le plugin de compatibilité. Il compose le plugin Intlayer de base, configure la surveillance du contenu, et — point critique — injecte des alias de module afin que vos appels existants import … from 'react-i18next' (et 'i18next') soient redirigés de manière transparente vers @intlayer/react-i18next / @intlayer/i18next lors de la construction. Aucun changement de fichier source n'est nécessaire.

   Pour Vite :

   vite.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
   
   export default defineConfig({
     plugins: [react(), reactI18nextVitePlugin()],
   });

   reactI18nextVitePlugin() enveloppe le plugin intlayer() de vite-intlayer et ajoute les alias react-i18next / i18next. L'utilisation du simple plugin intlayer() de vite-intlayer compile les dictionnaires mais n'ajoute pas ces alias — vous devrez alors renommer les imports vers @intlayer/* manuellement (voir l'étape 4).

   Pour Next.js :

   Si vous utilisez next-i18next (intégration Pages Router), installez @intlayer/next-i18next et next-intlayer :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npm install @intlayer/next-i18next next-intlayer

   Puis ajoutez le plugin de compatibilité à votre next.config.ts (il injecte les alias next-i18next / react-i18next / i18next) :

   next.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     /* vos options */
   };
   
   export default withIntlayer(nextConfig);

   Vous n'avez plus besoin de i18next.init() ou du bootstrap manuel du provider. Intlayer compile tous les dictionnaires au moment de la construction, il n'y a donc pas d'étape de chargement à l'exécution. Le provider aliasé gère l'initialisation pour vous.

C'est tout pour la migration rapide. Votre application fonctionne désormais sur Intlayer tout en conservant chaque import et API react-i18next intacts.

Clés de traduction typées — automatiques. Une fois qu'Intlayer a compilé vos dictionnaires, useTranslation et getFixedT sont typés par rapport à votre contenu réel. Les clés sont autocomplétées dans votre IDE et les chemins invalides provoquent des erreurs TypeScript au moment de la construction — aucune configuration supplémentaire n'est requise.

tsx

Copier le contenu

Copier le code

Copier le code dans le presse-papiers

// 'about' est une clé de dictionnaire enregistrée → t() n'accepte que des chemins validesconst { t } = useTranslation("about");t("counter.label"); // ✓ autocomplétét("does.not.exist"); // ✗ Erreur TypeScript// Côté serveur (instance i18next)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ typé

Migration complète

Les étapes ci-dessous sont facultatives et peuvent être effectuées de manière incrémentielle. Elles débloquent l'ensemble des fonctionnalités d'Intlayer : éditeur visuel, CMS, fichiers de contenu typés, traduction alimentée par l'IA, et plus encore.

1. 4

   Renommage explicite des imports (optionnel)

   Facultatif

   Les plugins Intlayer gèrent déjà l'aliassage au niveau du bundler. Si vous préférez rendre la dépendance explicite dans vos fichiers sources, vous pouvez renommer les imports manuellement :

   Afficher tout le contenu du tableau

   Afficher tout le contenu du tableau

   Ouvrir le tableau dans une fenêtre modale pour voir tout le contenu clairement

   Avant	Après
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   Pour Next.js (next-i18next) :

   Afficher tout le contenu du tableau

   Afficher tout le contenu du tableau

   Ouvrir le tableau dans une fenêtre modale pour voir tout le contenu clairement

   Avant	Après
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

   Activer l'automatisation de la traduction alimentée par l'IA

   Facultatif

   Une fois Intlayer configuré, utilisez sa CLI pour remplir automatiquement les traductions manquantes :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   # Tester les traductions manquantes (ajouter au CI)npx intlayer test# Remplir les traductions manquantes avec l'IAnpx intlayer fill

   Ajoutez la configuration de l'IA à intlayer.config.ts :

   intlayer.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // défaut
       // model: "gpt-4o-mini",   // défaut
     },
   };
   
   export default config;

   Consultez la documentation de la CLI Intlayer pour toutes les options disponibles.

Ce que vous pouvez supprimer après la migration

Une fois les adaptateurs de compatibilité en place, le code standard react-i18next / i18next suivant peut être supprimé :

Lorsque vous êtes prêt à aller plus loin, Intlayer découvre automatiquement tous les fichiers .content.ts et .content.json n'importe où dans votre base de code (par défaut, n'importe où dans ./src). Vous pouvez placer un fichier my-component.content.ts juste à côté de votre MyComponent.tsx et Intlayer le détectera au moment de la construction sans configuration supplémentaire — pas d'imports, pas d'enregistrement, pas besoin de fichier d'index centralisé. Cela rend la colocalisation des traductions avec les pages et les composants complètement transparente.

Configurer TypeScript

Intlayer utilise l'augmentation de module pour fournir une intellisense TypeScript complète pour vos clés de traduction. Assurez-vous que votre tsconfig.json inclut les types générés automatiquement :

{  // ... Vos configurations TypeScript existantes  "include": [    // ... Vos configurations TypeScript existantes    ".intlayer/**/*.ts", // Inclure les types générés automatiquement  ],}

Configuration Git

Ajoutez le répertoire généré par Intlayer à votre .gitignore :

# Ignorer les fichiers générés par Intlayer.intlayer

Aller plus loin

• Éditeur visuel — Gérez les traductions visuellement dans votre navigateur : Éditeur visuel Intlayer
• CMS — Externalisez et gérez le contenu à distance : Intlayer CMS
• Extension VS Code — Obtenez l'autocomplétion et la détection d'erreurs de traduction en temps réel : Extension VS Code Intlayer
• Référence CLI — Liste complète des commandes CLI : Intlayer CLI
• Intlayer avec React — Guide d'installation complet pour React : intlayerwithvite+react.md
• Intlayer avec Next.js — Guide d'installation complet pour Next.js : intlayerwithnextjs_16.md