Migrer de next-intl à Intlayer

Pourquoi migrer de next-intl à Intlayer ?

Stratégie de migration

L'approche recommandée pour les applications existantes est l'adaptateur de compatibilité : installez @intlayer/next-intl, qui expose exactement la même API que next-intl mais délègue tout le travail de traduction à Intlayer en coulisses.

Vous conservez vos useTranslations, getTranslations, NextIntlClientProvider existants et autres amis — le seul changement est le chemin d'importation. Aucun refactoring des signatures d'appel, des formes de prop ou de la structure des composants n'est requis.

Au fil du temps, vous pouvez optionnellement migrer des fichiers individuels vers le format .content.ts plus riche d'Intlayer pour débloquer l'éditeur visuel, le CMS et la portée du contenu par composant — mais cette étape est entièrement facultative et peut être effectuée de manière incrémentielle.

Table des Matières

Migration rapide

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

1. 1

   Installer les Dépendances

   Installez les packages principaux d'Intlayer et l'adaptateur de compatibilité @intlayer/next-intl :

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
   bun x intlayer init

   Gardez next-intl installé — il est toujours requis pour le routage URL (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). L'adaptateur de compatibilité ne remplace pas la couche de routage.

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 :

   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({
         // 'icu' correspond à la syntaxe d'espace réservé ICU de next-intl : {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   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: 'icu' garantit que les espaces réservés ICU comme {name} et {count, plural, one {# item} other {# items}} sont analysés correctement.

   Pour une liste complète des options de configuration, consultez la documentation de configuration.

3. 3

   Ajouter le Plugin Intlayer à Next.js

   Enveloppez votre configuration Next.js existante avec createNextIntlPlugin depuis @intlayer/next-intl/plugin. Cette enveloppe compose withIntlayer et enregistre les alias next-intl → @intlayer/next-intl pour vous :

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* vos options de configuration existantes */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() enveloppe withIntlayer, détecte automatiquement Webpack ou Turbopack, configure la surveillance du contenu, la compilation des dictionnaires et — point critique — injecte des alias de module afin que vos appels existants import … from 'next-intl' soient redirigés de manière transparente vers @intlayer/next-intl lors de la construction. L'entrée de routage next-intl/routing reste pointée vers le package réel. Aucun changement de fichier source n'est nécessaire.

   Préférez-vous le withIntlayer simple de next-intlayer/server ? Il compilera vos dictionnaires, mais n'ajoutera pas les alias next-intl — vous devrez alors renommer les imports vers @intlayer/next-intl manuellement (voir l'étape 4).

   Vous n'avez plus besoin de getRequestConfig ou de loadMessages. Avec next-intl, vous deviez écrire un fichier src/i18n.ts qui chargeait des bundles de messages JSON à chaque requête via getRequestConfig. Intlayer compile tous les dictionnaires au moment de la construction, il n'y a donc pas d'étape de chargement à l'exécution. Vous pouvez supprimer ce fichier entièrement (ou ne conserver que les parties de routage si vous utilisez toujours createNavigation).

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

Clés de traduction typées — automatiques. Une fois qu'Intlayer a compilé vos dictionnaires, useTranslations et getTranslations 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.

// Composant client — 'about' est une clé de dictionnaire enregistrée
const t = useTranslations("about");
t("counter.label"); // ✓ autocomplété
t("does.not.exist"); // ✗ Erreur TypeScript

// Composant serveur
const t = await getTranslations("about");
t("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

   L'enveloppe createNextIntlPlugin() gère déjà l'aliassage next-intl → @intlayer/next-intl au niveau du bundler. Si vous préférez rendre la dépendance explicite dans vos fichiers sources (et utiliser le plugin withIntlayer simple à la place), 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 { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Conservez toujours les imports de routage du vrai next-intl — l'adaptateur de compatibilité ne remplace pas la couche de routage URL :

   // ✅ Conservez toujours ceux-ci depuis le vrai 'next-intl'
   import { createNavigation } from "next-intl/routing";
   import { createMiddleware } from "next-intl/server";
   import { defineRouting } from "next-intl/routing";

   Alternativement, vous pouvez utiliser defineRouting depuis @intlayer/next-intl/routing qui fusionne automatiquement la configuration des paramètres régionaux de votre intlayer.config.ts.

2. 5

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

   Facultatif

   Une fois Intlayer configuré, vous pouvez utiliser sa CLI pour remplir automatiquement les traductions manquantes en utilisant le LLM de votre choix :

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

   pnpm intlayer test
   pnpm intlayer fill

   yarn intlayer test
   yarn intlayer fill

   bun x intlayer test
   bun x intlayer fill

   Ajoutez une clé OPENAI_API_KEY (ou la clé de votre fournisseur préféré) à votre fichier .env, puis étendez votre intlayer.config.ts :

   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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     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 @intlayer/next-intl en place, le code standard next-intl 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 about.content.ts juste à côté de votre about/page.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 Next.js — Guide d'installation complet pour Next.js : intlayerwithnextjs_16.md