i18next VS @intlayer/i18next: Même API, Bundle Différent

@intlayer/i18next, @intlayer/react-i18next et @intlayer/next-i18next sont des adaptateurs de compatibilité. Ils exposent l'API i18next que votre code utilise déjà (useTranslation, t(), <Trans>, i18n.changeLanguage(), getFixedT, serverSideTranslations...) et la distribuent à partir de dictionnaires compilés par Intlayer. Les composants ne changent pas. Le runtime sous-jacent, lui, change.

Cet article mesure ce remplacement sur la même application Next.js, construite une fois avec next-i18next et une fois avec @intlayer/next-i18next. Les chiffres proviennent de Benchmark Bloom. Pour comparer i18next et Intlayer en tant que bibliothèques distinctes, consultez i18next vs Intlayer. Celui-ci se concentre sur ce que l'adaptateur transforme lorsque vous conservez votre code tel quel.

tl;dr : Sur la même application Next.js, remplacer next-i18next par @intlayer/next-i18next fait passer le JavaScript par page de 218.5 Ko à 150.7 Ko gzip (configuration naïve) et surpasse la configuration next-i18next entièrement optimisée (163.4 Ko) de 12.7 Ko. Le composant moyen passe de 78.5 Ko à 9.7 Ko, la fuite de chaînes vers d'autres pages passe de ~90% à 0%, l'hydratation de 15.6 ms à 11.3 ms, et le runtime de 19.7 Ko à 9.4 Ko. Aucun composant n'a été modifié, un seul fichier de provider l'a été. Les plugins i18next (backends, détecteurs de langue) sont acceptés mais ne font rien : il n'y a plus rien à charger ni à détecter au runtime.

Ce qu'est @intlayer/i18next

i18next est un runtime. i18n.init({ resources }) ou un plugin backend charge locales/{lng}/{ns}.json dans une instance globale ; useTranslation("about") y abonne le composant ; t("title") recherche la clé au moment du rendu. Les namespaces, le lazy loading, les listes de namespaces par page et la sécurité de typage sont entièrement à votre charge en matière de configuration et de maintenance.

Les adaptateurs conservent l'API et remplacent l'instance :

1. Alias d'importation. createNextI18nPlugin() depuis @intlayer/next-i18next/plugin (ou withI18next) enveloppe withIntlayer et ajoute des alias Webpack / Turbopack pour que next-i18next, react-i18next et i18next renvoient vers leurs équivalents @intlayer/*. Sur Vite, reactI18nextVitePlugin() depuis @intlayer/react-i18next/plugin fait de même. Aucun import n'a besoin d'être renommé.
2. JSON comme source de vérité. Le plugin syncJSON lit vos fichiers existants locales/{lng}/{ns}.json avec format: "i18next" (ainsi {{name}}, l'imbrication $t(), les suffixes _one / _other et de contexte sont correctement analysés) et réécrit les traductions lorsque le CLI ou le CMS les met à jour.
3. Liaison sur le site d'appel. La passe d'optimisation d'Intlayer réécrit useTranslation("about") en un appel qui reçoit directement le dictionnaire about, dans la locale active. Le composant cesse d'interroger le store global.

// Votre code, inchangé
import { useTranslation } from "react-i18next";

const About = () => {
  const { t } = useTranslation("about");
  return <h1>{t("title")}</h1>;
};

import _dicHash_about from "../.intlayer/dictionaries/about.mjs";
import { useDictionary as useTranslation } from "@intlayer/react-i18next";

const About = () => {
  const { t } = useTranslation(_dicHash_about);
  return <h1>{t("title")}</h1>;
};

Cette réécriture est précisément ce qui fait basculer les colonnes de taille des composants et de fuite de page ci-dessous.

Ce que les adaptateurs conservent, ignorent et ne remplacent pas

Le benchmark

Ce qui a été mesuré

La suite Benchmark Bloom construit la même application avec chaque configuration : 10 pages (accueil, à propos, blog, carrières, contact, FAQ, tarifs, produits, paramètres, équipe), 10 locales (en, fr, es, de, it, pt, zh, ja, ko, ru), des composants identiques et un contenu identique. Les pages sont mesurées en en et fr.

next-i18next a été testé avec quatre stratégies de chargement, depuis le JSON de chaque locale importé dans resources (static) jusqu'à un namespace par route, chargé paresseusement via un backend (scoped-dynamic). L'adaptateur a été construit sur les mêmes composants que la configuration naïve, avec uniquement next.config.ts, intlayer.config.ts et le fichier de provider modifiés. Il ne propose aucune variante "scopée" manuelle : le compilateur scope le contenu par composant.

Pour chaque build, la suite enregistre :

• Taille de la lib : taille gzip d'un composant vide qui n'importe que la bibliothèque i18n.
• JS par page : moyenne du JavaScript gzip téléchargé par page sur toutes les pages et locales.
• % de fuite de locale : part des chaînes traduites dans le JS téléchargé qui appartiennent à une locale que l'utilisateur ne consulte pas.
• % de fuite de page : part des chaînes traduites dans le JS téléchargé qui appartiennent à une page sur laquelle l'utilisateur ne se trouve pas.
• Moyenne composant : taille moyenne gzip de chaque composant compilé isolément.
• Réactivité E2E : temps réel mesuré entre le choix d'une nouvelle locale et la mise à jour de html[lang] dans le DOM (Playwright, 5 itérations).
• Hydratation : durée de la phase d'hydratation de React.

Les chiffres ci-dessous proviennent de l'exécution du 12/09/2026 avec next-i18next 16.3.0 (react-i18next 17.0.13, i18next 26.4.2) et @intlayer/next-i18next 9.5.1. L'application de test est volontairement compacte (quelques dizaines de chaînes par locale), les pourcentages de fuite décrivent donc une tendance : ils croissent avec votre contenu tandis que le coût du runtime reste fixe.

Résultats sur Next.js

Sélectionnez les métriques et les bibliothèques qui vous intéressent :

Comment l'interpréter

• 68 Ko de moins par page par rapport à la configuration naïve. resources: { en, fr, ... } expédie chaque locale et chaque namespace sur chaque page : 218.5 Ko. Le build avec adaptateur pour les mêmes composants tombe à 150.7 Ko. Il surpasse également la meilleure configuration de next-i18next (163.4 Ko, un namespace par route, chargé à la demande) de 12.7 Ko, car le runtime i18next pèse à lui seul 19.7 Ko contre 9.4 Ko.
• La fuite passe à 0% sans toucher au moindre composant. Chaque configuration de next-i18next sauf la version entièrement découpée expédie ~90% de chaînes d'autres pages. La ligne dynamic est plus pénalisante qu'il n'y paraît : elle n'élimine pas la fuite de page et introduit 50% de fuite de locale, car le backend par locale rapatrie toujours l'intégralité du namespace translation. L'adaptateur atteint 0% / 0% directement sur le code d'origine.
• Composants : 8x plus légers. Un composant utilisant useTranslation() compilé isolément pèse en moyenne 78.5 Ko avec resources inliné et 26-27 Ko avec un backend, car t reste lié au store global. Avec l'adaptateur, il n'affiche plus que 9.7 Ko.
• Hydratation et basculement plus rapides. L'hydratation passe de 15.6 ms à 11.3 ms (et de 27.7 ms dans la configuration dynamic, où l'appel backend se situe sur le chemin critique). Le basculement de locale passe de 15-16 ms à 11-12 ms.
• L'adaptateur n'est pas le runtime natif. next-intlayer atteint 141.3 Ko, soit +0.3 Ko par rapport à l'application de base. L'adaptateur supporte la surface d'API de i18next (dialecte d'interpolation, résolution des pluriels et contextes, analyse des balises <Trans>) en surcouche du cœur d'Intlayer : 9.4 Ko et +9.4 Ko par page par rapport au natif. Il constitue une passerelle, non une fin en soi.

Tableau complet, chaque bibliothèque et chaque stratégie, dans le rapport de benchmark Next.js.

Résultats sur TanStack Start (react-i18next)

Pour Vite et TanStack Start, le benchmark compare react-i18next seul à intlayer :

Tableau complet dans le rapport de benchmark TanStack Start.

L'adaptateur react-i18next sur Vite / TanStack Start n'a pas été inclus dans ce cycle de test. La référence pour react-i18next sur TanStack Start se trouve dans i18next vs Intlayer : 127-184 Ko par page et 123-185 ms de temps de basculement de locale quand le backend est différé.

Pourquoi ces écarts de métriques

Rien n'a changé dans le dossier components/ : les gains proviennent donc exclusivement de la cible à laquelle useTranslation est relié.

Avec i18next, la liaison s'établit avec l'instance globale. Tout ce qui y a été chargé (toutes les locales en static, l'ensemble du namespace de la locale active en dynamic) est accessible depuis chaque composant appelant useTranslation(). Le bundler ne peut pas découper plus finement que ce que l'instance retient, et le runtime ne peut pas anticiper les clés demandées au rendu.

.
├── next-i18next.config.js
├── public/locales
│   ├── en/translation.json           # toutes les chaînes de chaque page
│   └── fr/translation.json
├── i18n/i18n.ts                      # i18n.use(initReactI18next).init({ resources })
└── components
    ├── AppProviders.tsx              # <I18nextProvider i18n={i18n}>
    └── About.tsx                     # useTranslation(); t("about.title")

Tout ce que l'instance contient est expédié sur chaque page, et le gaspillage croît sur deux axes, les pages et les locales :

Avec @intlayer/next-i18next, la liaison s'opère directement avec le dictionnaire. syncJSON convertit chaque fichier de namespace en dictionnaire ; la passe d'optimisation transmet au composant le dictionnaire correspondant sous forme d'un import que le bundler peut tracer et séparer par page et par locale.

.
├── intlayer.config.ts                # syncJSON({ format: "i18next", source: ... })
├── public/locales
│   ├── en/translation.json           # inchangé, toujours source de vérité
│   └── fr/translation.json
├── .intlayer/                        # généré : un dictionnaire par namespace, par locale
└── components
    ├── AppProviders.tsx              # <IntlayerClientProvider locale={locale}>
    └── About.tsx                     # useTranslation(); t("about.title")  ← inchangé

Le fichier i18n/i18n.ts et son import de resources deviennent du code mort. C'est là que résident les 68 Ko d'économie.

Migration en trois étapes

1. 1

   Installation

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npx intlayer init --interactive
   

   La commande détecte i18next / react-i18next / next-i18next, installe intlayer, le package de framework (next-intlayer ou react-intlayer), l'adaptateur @intlayer/* correspondant ainsi que @intlayer/sync-json-plugin, et pré-remplit intlayer.config.ts. Laissez les packages d'origine installés : ils servent de peer dependencies et fournissent les définitions de types.

2. 2

   Pointer Intlayer vers vos fichiers de locales

   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,
     },
     dictionary: {
       importMode: "dynamic",
       format: "i18next",
     },
     plugins: [
       syncJSON({
         // dialecte i18next : {{name}}, $t(key), key_one / key_other, key_male
         format: "i18next",
         // Un fichier par namespace : `useTranslation("about")` → about.json
         source: ({ locale, key }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;
   

   Si vous disposez d'un unique fichier translation.json par locale (le namespace par défaut d'i18next), définissez splitKeys: false afin que le fichier complet reste un seul dictionnaire et qu'un appel simple à useTranslation() continue de fonctionner.

3. 3

   Ajouter le plugin

   Next.jsVite / TanStack Start

   next.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { NextConfig } from "next";
   import { withI18next } from "@intlayer/next-i18next/plugin";
   
   const nextConfig: NextConfig = {};
   
   export default withI18next(nextConfig);
   

   Sur l'App Router, les composants clients obtiennent leur locale via le segment [locale]. L'I18nextProvider de l'adaptateur ne prenant aucune locale en paramètre, remplacez-le une seule fois dans votre fichier de provider :

   components/AppProviders.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   "use client";
   
   import { IntlayerClientProvider } from "next-intlayer";
   import type { LocalesValues } from "intlayer";
   
   export const AppProviders = ({
     locale,
     children,
   }: {
     locale: LocalesValues;
     children: React.ReactNode;
   }) => (
     <IntlayerClientProvider locale={locale}>{children}</IntlayerClientProvider>
   );
   

   Tous les composants enfants continuent d'appeler useTranslation() sans modification.

   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 vite-intlayer et crée les alias pour react-i18next et i18next. Pour un projet sans React, i18nextVitePlugin() depuis @intlayer/i18next/plugin crée l'alias pour i18next seul.

Ce que vous pouvez supprimer par la suite

Ce que vous gagnez au-delà des octets

• Clés typées. useTranslation("about") est typé d'après le dictionnaire compilé about ; t("does.not.exist") déclenche une erreur TypeScript au lieu de renvoyer la chaîne de clé.
• npx intlayer test bloque la CI en cas de clé manquante dans n'importe quelle langue. npx intlayer fill traduit automatiquement les clés manquantes avec votre propre clé d'API (OpenAI, Anthropic, Mistral, Gemini...) et les réécrit dans locales/{lng}/{ns}.json.
• Éditeur visuel et CMS opèrent sur le même JSON, permettant aux équipes éditoriales de modifier le contenu via une interface pendant que les fichiers se mettent à jour.
• Transition progressive vers .content.ts. Chaque composant peut basculer indépendamment de useTranslation("about") à useIntlayer("about") avec un fichier de contenu dédié. Fichiers JSON et .content.ts coexistent naturellement.

Limites à connaître avant de démarrer

Comparaison des fonctionnalités

Au-delà des octets, ce que chaque option vous apporte :

Les tailles de runtime proviennent de l'exécution Next.js décrite plus haut.

Quand choisir quelle solution ?

FAQ

Comparatifs associés

Même série d'adaptateurs :

Les bibliothèques comparées directement :

Documentation de référence :

Compat adapters:

Migration guides:

Pour comprendre d'où viennent ces bibliothèques, lisez l'histoire de l'i18n en JavaScript.

Conclusion

i18next constitue le runtime le plus lourd de ce benchmark, et les adaptateurs en retirent la majeure partie sans vous obliger à quitter son API. Sur la même application Next.js, cela représente 68 Ko de moins par page par rapport à la configuration naïve, 12.7 Ko de moins que la version la plus optimisée à la main, des composants 8x plus légers, 0% de fuite et 4 ms d'hydratation, le tout en échange d'un fichier de configuration, d'une ligne de plugin et d'un ajustement de provider. Les backends et détecteurs deviennent sans effet, resources est ignoré plutôt que fusionné, et le runtime natif next-intlayer conserve 9 Ko d'avance supplémentaire en légèreté.

L'ensemble des données brutes, des applications de test et des scripts est disponible dans le dépôt Benchmark Bloom. Vous pouvez le reproduire vous-même.

Consultez le document Pourquoi Intlayer ? pour en savoir plus.