@intlayer/docs 8.7.4 → 8.7.5

package/docs/en/benchmark/___nextjs.md

@@ -0,0 +1,195 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Best i18n solution for Next.js in 2026 - Benchmark Report
+description: Compare Next.js internationalization (i18n) libraries like next-intl, next-i18next, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - performance
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author: Aymeric PINEAU
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Next.js i18n Libraries — 2026 Benchmark Report
+
+Cette page est un rapport de benchmark pour les solutions i18n pour Next.js.
+
+## Table of Contents
+
+<Toc/>
+
+## Interactive Benchmark
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Results reference:
+
+<iframe 
+  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md" 
+  width="100%" 
+  height="600px"
+  style="border:none;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md
+
+## Introduction
+
+Les solution d'internationalization sont des librairies impactantes pour votre application. Le risque principal est de faire charger le contenu de toutes les pages et dans toutes les langues pour une seule page consultée.
+
+Au moment ou votre application grandit, la taille du bundle va evoluer exponentiellement, ce qui peut significativement ralentir les performances de votre application.
+
+En guise d'example, pour les plus mauvais elèves, une fois internationalisée, votre page peut se retrouver pres de 4x plus volumineuse.
+
+Un autre impact des solution d'internationalization est le ralentissement du developement. Transformer vos components et organizer vos contenu dans toutes les langues, est chonophage.
+
+Le probleme etant complexe, un grand nombres de solutions ont vu le jour pour resoudre le probleme de l'i18n. Certaines solutions se focusant sur la DX, d'autres sur la performance, d'autres sur la scalabilite, etc.
+
+Intlayer est une solution tentant d'optimiser l'ensemble de ces aspects.
+
+## Teste ton application
+
+Pour deteacter ces problematiques, j'ai mis en place un scanner gratuit que vous pouvez tester [ici](https://intlayer.org/i18n-seo-scanner).
+
+## Problematic
+
+Il existe deux grands aspects pour limiter l'impact d'une application multilingue sur le bundle de l'application:
+
+- Diviser vos JSON (ou contenu) en plusieurs fichiers / variables / namespaces pour permettre au bundler de tree-shaker le contenu non utilisé dans votre page
+- Loader dynamicement le contenu de votre page uniquement dans la langue de la page
+
+Comprendre les limitations techniques pour ces approaches:
+
+**Dynamic loading**
+
+Meme en declarant vos routes tel que `[locale]/page.tsx`, que ce soit avec Webpack ou Turbopack, et bien que `getStaticParams` soit definie, le bundler de traite pas `locale` comme une variable statique. Cela signifie que le bundler va charger le contenu de toutes les langues pour chaque page. La seule option pour limiter ce probleme est de faire charger le contenu via un import dynamic (e.g. `import('./locales/${locale}.json')`).
+
+Ce qu'il se passe au moment du build, c'est que Next.js va generer un fichier JS (bundle) pour chaque langue (e.g. `./locales_fr_12345.js`). Puis apres que le site soit envoyé au client, au moment ou la page est executée, c'est le browser qui va se changera d'efectuer une requette HTTP supplémentaire, demandant le fichier JS requis (e.g. `./locales_fr_12345.js`).
+
+> Un autre moyen de repondre au meme probleme est d'utiliser la methode `fetch()` pour requester le fichier JSON dynamiquement. C'est le cas de `Tolgee` via le fait de placer les JSON dans le docier `/public` ou bien `next-transalte`, qui se base sur la fonction `getStaticProps` pour charger le contenu. Mais le flow reste le meme, le browser va faire une requette HTTP supplémentaire pour charger l'asset.
+
+**Split du contenu**
+
+Si vous utiliser une syntax tel que `const t = useTranslation()` + `t('my-object.my-sub-object.my-key')`, le JSON doit etre integralement chargé dans le bundle, pour ensuite etre parsé par la librairie afin d'en deduire la valeur de la clé. Or cela signifie qu'une grande partie du contenu sera chargée dans votre bundle, bien que non utilisé dans la page.
+
+Pour repondre a ce probleme, certaines librairies suggerent de declarer manuellement pour chaque page quelles namespaces doivent etre chargées. C'est le cas de `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`.
+
+En compaison, `Paraglide` propose l'ajout d'une etape supplimentaire, avant le build pour transformer le JSON en flat variable, tel que `const en_my_var = () => 'my value'`. Cela permet (en théorie) de tree-shaker le contenu non utilisé dans la page. Mais on le vera, cette methode n'est pas sans compromis.
+
+Enfin, `Intlayer` propose une opitimization au build-time, permettant replacer l'usage de `useIntlayer('my-key')` et d'y attacher directement le contenu correspondant.
+
+## Methodology
+
+Pour ce benchmark, nous avons comparé les librairies suivantes:
+
+- `Base App` (No i18n library)
+- `next-intlayer` (v8.7.5)
+- `next-i18next` (v16.0.5)
+- `next-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `next-translate` (v3.1.2)
+- `next-international` (v1.3.1)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `@lingo.dev/compiler` (v0.4.0)
+- `wuchale` (v0.22.11)
+- `gt-next` (v6.16.5)
+
+J'ai utilisé le framework `Next.js` version `16.2.4` avec le mode `app router`.
+
+J'ai créé une application multilingue avec **10 pages**, dans **10 langues**.
+
+Et j'ai comparé **4 strategies de chargement**:
+
+| Stratégie              | Pas de Namespaces (Global)                        | Avec Namespaces (Scoped)                                                |
+| :--------------------- | :------------------------------------------------ | :---------------------------------------------------------------------- |
+| **Chargement Static**  | **Static** : Tout en mémoire au démarrage.        | **Scoped Static** : Segmenté par namespace, tout chargé au démarrage.   |
+| **Chargement Dynamic** | **Dynamic** : Chargement à la demande par locale. | **Scoped Dynamic** : Chargement granulaire par namespace et par locale. |
+
+## Synthèse des stratégies
+
+- **Static** : Simple, aucune latence réseau après le chargement initial. Inconvénient : bundle size élevé.
+- **Dynamic** : Réduit le poids initial (lazy-loading). Idéal pour un grand nombre de locales.
+- **Scoped Static** : Permet une organisation propre du code (séparation logique) sans surcoût de requêtes réseau complexes.
+- **Scoped Dynamic** : Approche optimale pour le _Code Splitting_ et la performance. Minimise la charge mémoire en ne chargeant que le strict nécessaire pour la vue courante et la locale active.
+
+## Details des Resultats
+
+### 1 - Les solutions a fuire
+
+Certaines solutions tel que `gt-next` ou `lingo.dev` sont clairement des solutions à éviter. C'est solutions integrent un combo vendor lock-in + poisonning de votre codebase. Et le comble etant que malgré de nombreuse heures a tenrer des les implementer, je n'ai jamais reussi a les faire fonctionner. Que ce soit pour Tanstack start ou Next.js.
+Liste de problemes rencontrés:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- Pour une application 110kb, `gt-react` y ajoute plus de 440kb additionel.
+- `Quota Exceeded, please upgrade your plan`, dès le premier build avec la solution de general ransaltion.
+- Translations are not rendered; I get the error `Error: <T> used on the client-side outside of <GTProvider>`, which seems to be a bug in the library.
+- While implementing **gt-tanstack-start-react**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
+- The library blocks static rendering of Next.js pages.
+
+**(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
+
+- Quota AI dépassé, bloquant totalement le build. Il est alors impossible de push en production sans payer.
+- The compiler was missing almost 40% of the translated content. I had to rewrite all `.map` into flat component blocks to make it work.
+- Their CLI is buggy. and used to rezet the config file with no reason.
+- At build, it totally erase the generated JSONs when there is new content added. As a result, you have only one 3 keys erasing >300 existing keys.
+
+### 2 - Les solutions experimentales
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+L'idee de `Wuchale` est interessante, mais n'est pas encore au stade de solution viable. J'ai rencontré des problemes de reactivity avec la librairie, et ai du forcer le rerendering de la provider pour faire fonctionner l'application. La documentation est aussi relativement peu claire, complexifant la prise en main.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` est une solution offrant une approache inovante, et bien pensée. Pour autant, dans le cadre de mon benchmark, on se rend compte que le tree-shaking que vend leur entreprise ne fonctionne ni pour mon implementation de Next.js, ni pour Tanstack start. Le flow et la DX est également plus complexe que les autres solutions. Et je ne suis personellement pas fan du fait de devoir regerer des fichiers JS avant chaque push, créant un risque de conflits constant entre les developpeurs via leur PR. Enfin, la solution semble davantage se focaliser sur Vite que sur Next.js.
+
+### 3 - Les solutions 'ok'
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` est une solution repondant aux different problemes evoqués plus tot. Mais j'ai trouvé la prise en main de la solution plus complexe que les autres solutions propsant des approches similaires. La solution ne propose pas de typesafety. Ce qui rend aussi la detection des clés manquantes a la compilation bien plus complexe. J'ai du rewraper les functions de Tolgee par les miennes pour y ajouter la detection de clés manquantes.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` est la solution la plus en vogue, et aussi la plus mise en avant les agent AI, mais selon moi a tord. Le get-started est assez simple. Mais en pratique, le process d'optimization pour limiter le leakage est assez complexe. De meme, la cohabitation du dynamic loading + namespacing + typescript types ralentit enormement le developpement. De plus, librairie est assez lourde (~13kb pour `NextIntlClientProvider` + `useTranslations` hook, ce qui est >2x plus lourde que `next-intlayer`). **next-intl** used to block static rendering of Next.js pages. It provides a fix function named `setRequestLocale()`. This issue seems to have been partially solved for centralized content such as `en.json` / `fr.json` / etc. But the solution still blocks static rendering when content is scoped into namespaces such as `en/shared.json` / `fr/shared.json` / `es/shared.json` / etc.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` est probablement la solution la plus populaire par le fait que ce soit la premiere solution a avoir vu le jour pour repondre aux besoins d'internationalisation d'application Javascript. Cette solution propose aussi un tat de pluggins communautaires pour repondre a certaines problematiques. Pour autant, cette solution presente les exactes meme points noirs que `next-intl`. De plus, librairie est particuliement lourde (~18kb pour `I18nProvider` + `useTranslation` hook, ce qui est 3x plus lourde que `next-intlayer`).
+Aussi, les formats de messages divergent entre les librairies. `next-intl` utilise le format ICU MessageFormat, alors que `i18next` utilise son propre format.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` est une solution repondant aussi aux different problemes evoqués plus tot, mais ne propose pas de difference significatif en rapport a `next-intl`, ou meme `next-i18next`. La solution inclut une fonction `scopedT()` qui permet de traduire le contenu dans un namespace spécifique. Cependant, l'utilisation de cette fonction n'a purement et simplement aucun impact sur la taille du bundle.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` est une solution pour laquelle j'ai entendu beaucoup de bien. Mais j'ai personnellement trouvé le flow basé sur l'execution de commandes `lingui extract` / `lingui compile` plus complexe que les autres approches, sans vrai avantage significatif. J'ai aussi noté le mangue d'armonie entre les syntaxes qui porte les IA a confution. (e.g. `t()`, `t''`, `i18n.t()`, `<Trans>`)
+
+### 4 - Mes recommendations
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` est ici ma principale recommandation pour ceux aimant l'usage d'une fonction `t()` pour traduire leur contenu. Cette solution offre une approche elegante via `next-transalte-plugin`, optimisant le loading de vos namespaces via `getStaticProps` via un loader Webpack / Turbopack. C'est aussi la solution la plus légère de toute (~2.5kb only). For namespacing, picking namespaces at the config level is also well thought out: you can define namespaces for each page or route. It makes maintenance much easier than the main alternatives, such as **next-intl** or **next-i18next**. Cependant j'ai noté qu'en version `3.1.2`, le build en static rendering ne fonctionne pas. Next.js fallback alors sur le dynamic rendering.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+Enfin, je ne jugerais pas personellement `next-intlayer`, par soucis d'objectivité, etant donnée qu'il s'agit de ma propre solution.
+
+### Personal note
+
+Cette note est personnelle et n'a pas d'impact sur les resultats du benchmark. Cependant, dans le monde de l'i18n on voit un concensus clair qui est d'utiliser une syntax tel que `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` pour traduire leur contenu.
+Cependant, dans le cadre d'appplication React, l'injection d'une fonction sous forme de `ReactNode` est selon moi un anti-pattern. De plus, cela introduit une complexité additionnel, pouvant etre evitée, et un overhead de JavaScript execution (bien qu'imperceptible).

package/docs/en/benchmark/___tanstack.md

@@ -0,0 +1,187 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Best i18n solution for TanStack Start in 2026 - Benchmark Report
+description: Compare TanStack Start internationalization libraries like react-i18next, use-intl, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - performance
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# TanStack Start i18n Libraries — 2026 Benchmark Report
+
+Cette page est un rapport de benchmark pour les solutions i18n pour TanStack Start.
+
+## Table of Contents
+
+<Toc/>
+
+## Interactive Benchmark
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+## Results reference:
+
+<iframe 
+  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md" 
+  width="100%" 
+  height="600px"
+  style="border:none;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md
+
+## Introduction
+
+Les solutions d'internationalisation font partie des dependances les plus impactantes pour une application React. Sur TanStack Start, le risque principal est de charger du contenu inutile: des traductions d'autres pages et d'autres locales dans le bundle d'une seule route.
+
+Au fur et a mesure que votre application grandit, ce probleme peut vite faire exploser le JavaScript envoye au client et ralentir la navigation.
+
+En pratique, pour les implementations les moins optimisees, une page internationalisee peut devenir plusieurs fois plus lourde que la version sans i18n.
+
+L'autre impact est sur la DX: declaration des contenus, types, organisation par namespaces, chargement dynamique, et gestion de la reactivite au changement de locale.
+
+## Teste ton application
+
+Pour detecter rapidement les problemes de leakage i18n, j'ai mis en place un scanner gratuit disponible [ici](https://intlayer.org/i18n-seo-scanner).
+
+## Problematic
+
+Deux axes sont essentiels pour limiter l'impact d'une application multilingue:
+
+- Splitter le contenu par page / namespace pour eviter de charger des dictionnaires entiers inutilement
+- Charger dynamiquement la bonne locale uniquement quand necessaire
+
+Comprendre les limitations techniques de ces approches:
+
+**Dynamic loading**
+
+Sans chargement dynamique, la plupart des solutions incluent les messages en memoire des le premier rendu, ce qui cree un surcout important pour les applications avec beaucoup de routes et de locales.
+
+Avec un chargement dynamique, il faut accepter un compromis: moins de JS initial, mais parfois une requete additionnelle au changement de langue.
+
+**Split du contenu**
+
+Les syntaxes basees sur `const t = useTranslation()` + `t('a.b.c')` sont tres pratiques mais poussent souvent a conserver de gros objets JSON en runtime. Ce modele rend le tree-shaking difficile si la bibliotheque ne propose pas une vraie strategie de split par page.
+
+## Methodology
+
+Pour ce benchmark, nous avons compare les librairies suivantes:
+
+- `Base App` (No i18n library)
+- `react-intlayer` (v8.7.5-canary.0)
+- `react-i18next` (v17.0.2)
+- `use-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `react-intl` (v10.1.1)
+- `wuchale` (v0.22.11)
+- `gt-react` (vlatest)
+- `lingo.dev` (v0.133.9)
+
+Le framework utilise est `TanStack Start` avec une application multilingue de **10 pages** et **10 langues**.
+
+Et nous avons comparé **4 stratégies de chargement** :
+
+| Stratégie              | Pas de Namespaces (Global)                        | Avec Namespaces (Scoped)                                                |
+| :--------------------- | :------------------------------------------------ | :---------------------------------------------------------------------- |
+| **Chargement Static**  | **Static** : Tout en mémoire au démarrage.        | **Scoped Static** : Segmenté par namespace, tout chargé au démarrage.   |
+| **Chargement Dynamic** | **Dynamic** : Chargement à la demande par locale. | **Scoped Dynamic** : Chargement granulaire par namespace et par locale. |
+
+## Synthèse des stratégies
+
+- **Static** : Simple, aucune latence réseau après le chargement initial. Inconvénient : bundle size élevé.
+- **Dynamic** : Réduit le poids initial (lazy-loading). Idéal pour un grand nombre de locales.
+- **Scoped Static** : Permet une organisation propre du code (séparation logique) sans surcoût de requêtes réseau complexes.
+- **Scoped Dynamic** : Approche optimale pour le _Code Splitting_ et la performance. Minimise la charge mémoire en ne chargeant que le strict nécessaire pour la vue courante et la locale active.
+
+## Details des Resultats
+
+### 1 - Les solutions a fuire
+
+Certaines solutions tel que `gt-react` ou `lingo.dev` sont clairement des solutions à éviter. Ces solutions intègrent un combo vendor lock-in + empoisonnement de votre codebase. Et le comble étant que malgré de nombreuses heures à tenter de les implémenter, je n'ai jamais réussi à les faire fonctionner correctement sur TanStack Start (comme sur Next.js pour `gt-next`).
+
+Liste de problèmes rencontrés :
+
+**(General Translation)** (`gt-react@latest`) :
+
+- Pour une application ~110kb, `gt-react` peut y ajouter plus de 440kb additionnel (ordre de grandeur observé sur l'implémentation Next.js du même benchmark).
+- `Quota Exceeded, please upgrade your plan`, dès le premier build avec la solution General Translation.
+- Translations are not rendered; I get the error `Error: <T> used on the client-side outside of <GTProvider>`, which seems to be a bug in the library.
+- While implementing **gt-tanstack-start-react**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
+- These libraries use an anti-pattern through the `initializeGT()` function, blocking the bundle from tree-shaking cleanly.
+
+**(Lingo.dev)** (`lingo.dev@0.133.9`) :
+
+- Quota AI dépassé (ou dépendance serveur bloquante), rendant le flux de build / prod risqué sans payer.
+- The compiler was missing almost 40% of the translated content. I had to rewrite all `.map` into flat component blocks to make it work.
+- Their CLI is buggy and used to reset the config file with no reason.
+- At build, it totally erased the generated JSONs when there was new content added. As a result, you could end up with only a few keys erasing hundreds of existing keys.
+- I met reactivity issues with the library on TanStack Start: on locale change I had to force rerendering of the provider to make it work.
+
+### 2 - Les solutions experimentales
+
+**(Wuchale)** (`wuchale@0.22.11`) :
+
+L'idée de `Wuchale` est intéressante, mais n'est pas encore au stade de solution viable. J'ai rencontré des problèmes de réactivité avec la librairie, et ai dû forcer le rerendering de la provider pour faire fonctionner l'application sur TanStack Start. La documentation est aussi relativement peu claire, complexifiant la prise en main.
+
+### 3 - Les solutions 'ok'
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`) :
+
+`Paraglide` est une solution offrant une approche innovante, et bien pensée. Pour autant, dans le cadre de mon benchmark, on se rend compte que le tree-shaking que vend leur entreprise ne fonctionne ni pour mon implémentation Next.js, ni pour TanStack Start. Le flow et la DX est également plus complexe que les autres solutions. Et je ne suis personnellement pas fan du fait de devoir régénérer des fichiers JS avant chaque push, créant un risque de conflits constant entre les développeurs via leur PR.
+
+**(Tolgee)** (`tolgee@7.0.0`) :
+
+`Tolgee` est une solution répondant aux différents problèmes évoqués plus tôt. Mais j'ai trouvé la prise en main de la solution plus complexe que les autres solutions proposant des approches similaires. La solution ne propose pas de typesafety. Ce qui rend aussi la détection des clés manquantes à la compilation bien plus complexe. J'ai dû ré-encapsuler les fonctions de Tolgee par les miennes pour y ajouter la détection de clés manquantes.
+
+Sur TanStack Start, j'ai aussi rencontré des problèmes de réactivité : au changement de locale j'ai dû forcer le rerendering du provider, et m'abonner aux événements de changement de locale pour que le chargement dans une autre langue se comporte correctement.
+
+**(use-intl)** (`use-intl@4.9.1`) :
+
+`use-intl` est la brique « intl » la plus en vogue dans l'écosystème React (même famille que `next-intl`), et aussi une des plus mise en avant par les agents AI, mais selon moi à tort dans un contexte performance-first. Le get-started est assez simple. Mais en pratique, le process d'optimisation pour limiter le leakage est assez complexe. De même, la cohabitation du dynamic loading + namespacing + TypeScript types ralentit énormément le développement.
+
+Sur TanStack Start, vous n'avez pas les pièges spécifiques à Next.js (`setRequestLocale`, static rendering), mais vous gardez le même coeur du problème : sans discipline stricte, le bundle embarque vite trop de messages et la maintenance des namespaces par route devient vite pénible.
+
+**(react-i18next)** (`react-i18next@17.0.2`) :
+
+`react-i18next` est probablement la solution la plus populaire par le fait que ce soit l'une des premières à avoir répondu aux besoins d'internationalisation d'applications JavaScript. Cette solution propose aussi tout un tas de plugins communautaires pour répondre à certaines problématiques.
+
+Pour autant, cette solution présente les mêmes grands points noirs que les stacks basées sur une fonction `t('a.b.c')` : optimisations possibles mais extrêmement chronophages, et risque élevé de mauvaises pratiques sur les gros projets (namespaces + chargement dynamique + types).
+
+De plus, les formats de messages divergent : `use-intl` s'appuie sur le format ICU MessageFormat, alors que `i18next` utilise son propre format — ce qui complique encore plus si vous mélangez outillage ou migrations.
+
+**(Lingui)** (`@lingui/core@5.3.0`) :
+
+`Lingui` est une solution pour laquelle j'ai entendu beaucoup de bien. Mais j'ai personnellement trouvé le flow basé sur l'exécution de commandes `lingui extract` / `lingui compile` plus complexe que les autres approches, sans vrai avantage significatif dans ce benchmark TanStack Start. J'ai aussi noté le manque d'harmonie entre les syntaxes qui porte les IA à confusion (e.g. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+**(react-intl)** (`react-intl@10.1.1`) :
+
+`react-intl` est une implémentation performante, produite par l'équipe Format.js. En revanche, la DX reste verbeuse : `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` introduit de la complexité, un surcoût d'exécution JavaScript, et connecte l'instance i18n globale à beaucoup de nœuds du graphe React.
+
+### 4 - Mes recommendations
+
+Ce benchmark TanStack Start ne contient pas d'équivalent direct à `next-translate` (plugin Next.js + `getStaticProps`). Pour les équipes qui veulent absolument une API `t()` avec un écosystème mature, `react-i18next` et `use-intl` restent des choix « raisonnables », mais attendez-vous à investir beaucoup de temps dans l'optimisation pour éviter le leakage.
+
+**(Intlayer)** (`react-intlayer@8.7.5-canary.0`) :
+
+Enfin, je ne jugerais pas personnellement `react-intlayer`, par souci d'objectivité, étant donné qu'il s'agit de ma propre solution.
+
+### Personal note
+
+Cette note est personnelle et n'a pas d'impact sur les résultats du benchmark. Cependant, dans le monde de l'i18n on voit un consensus clair qui est d'utiliser une syntaxe telle que `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` pour traduire leur contenu.
+
+Cependant, dans le cadre d'applications React, l'injection d'une fonction sous forme de `ReactNode` est selon moi un anti-pattern. De plus, cela introduit une complexité additionnelle, pouvant être évitée, et un overhead de JavaScript execution (bien qu'imperceptible).

package/docs/en/benchmark/index.md

@@ -0,0 +1,29 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-20
+title: Benchmark i18n libraries
+description: Learn how Intlayer compares to other i18n libraries in terms of performance and bundle size.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - tanstack
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Benchmark - Report
+
+Benchmark Bloom is a performance benchmarking suite that measures the real-world impact of i18n (internationalization) libraries across multiple React frameworks and loading strategies.
+
+Find the detailed reports and technical documentation for each framework below:
+
+- [**Next.js Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md)
+- [**TanStack Start Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/tanstack.md)

package/docs/en/benchmark/nextjs.md

@@ -0,0 +1,228 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Best i18n solution for Next.js in 2026 - Benchmark Report
+description: Compare Next.js internationalization (i18n) libraries like next-intl, next-i18next, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - performance
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Next.js i18n Libraries - 2026 Benchmark Report
+
+This page is a benchmark report for i18n solutions on Next.js.
+
+## Table of Contents
+
+<Toc/>
+
+## Interactive Benchmark
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Results reference:
+
+<iframe 
+  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md" 
+  width="100%" 
+  height="600px"
+  style="border:none;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md
+
+See complete benchmark repository [here](https://github.com/intlayer-org/benchmark-i18n).
+
+## Introduction
+
+Internationalization libraries have a heavy impact on your application. The main risk is loading content for every page and every language when the user only visits one page.
+
+As your app grows, bundle size can grow exponentially, which can noticeably hurt performance.
+
+As an example, for the worst offenders, once internationalized your page can end up nearly 4× larger.
+
+Another impact of i18n libraries is slower development. Turning components into multilingual content across languages is time-consuming.
+
+Because the problem is hard, many solutions exist—some focused on DX, others on performance or scalability, and so on.
+
+Intlayer tries to optimize across these dimensions.
+
+## Test your app
+
+To surface these issues, I built a free scanner you can try [here](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## The problem
+
+There are two major ways to limit the impact of a multilingual app on your bundle:
+
+- Split your JSON (or content) across files / variables / namespaces so the bundler can tree-shake unused content for a given page
+- Dynamically load your page content only in the page’s language
+
+Technical limitations for these approaches:
+
+**Dynamic loading**
+
+Even when you declare routes like `[locale]/page.tsx`, with Webpack or Turbopack, and even if `generateStaticParams` is defined, the bundler does not treat `locale` as a static constant. That means it may pull content for all languages into each page. The main way to limit this is to load content via a dynamic import (e.g. `import('./locales/${locale}.json')`).
+
+What happens at build time is that Next.js emits one JS bundle per locale (e.g. `./locales_fr_12345.js`). After the site is sent to the client, when the page runs, the browser performs an extra HTTP request for the needed JS file (e.g. `./locales_fr_12345.js`).
+
+> Another way to address the same problem is to use `fetch()` to load JSON dynamically. That is how `Tolgee` works when JSON lives under `/public`, or `next-translate`, which relies on `getStaticProps` to load content. The flow is the same: the browser makes an extra HTTP request to load the asset.
+
+**Content splitting**
+
+If you use syntax like `const t = useTranslation()` + `t('my-object.my-sub-object.my-key')`, the entire JSON usually has to be in the bundle so the library can parse it and resolve the key. Much of that content then ships even when it is unused on the page.
+
+To mitigate this, some libraries ask you to declare per page which namespaces to load, e.g. `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`.
+
+By contrast, `Paraglide` adds an extra step before build to turn JSON into flat symbols like `const en_my_var = () => 'my value'`. In theory that enables tree-shaking unused content on the page. As we will see, that method still has trade-offs.
+
+Finally, `Intlayer` applies a build-time optimization so `useIntlayer('my-key')` is replaced with the corresponding content directly.
+
+## Methodology
+
+For this benchmark, we compared the following libraries:
+
+- `Base App` (No i18n library)
+- `next-intlayer` (v8.7.5)
+- `next-i18next` (v16.0.5)
+- `next-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `next-translate` (v3.1.2)
+- `next-international` (v1.3.1)
+- `@inlang/paraglide-js` (v2.15.1)
+- `@tolgee/react` (v7.0.0)
+- `@lingo.dev/compiler` (v0.4.0)
+- `wuchale` (v0.22.11)
+- `gt-next` (v6.16.5)
+
+I used `Next.js` version `16.2.4` with the App Router.
+
+I built a multilingual app with **10 pages** and **10 languages**.
+
+I compared **four loading strategies**:
+
+| Strategy            | No namespaces (global)                       | With namespaces (scoped)                                             |
+| :------------------ | :------------------------------------------- | :------------------------------------------------------------------- |
+| **Static loading**  | **Static**: Everything in memory at startup. | **Scoped static**: Split by namespace; everything loaded at startup. |
+| **Dynamic loading** | **Dynamic**: On-demand loading per locale.   | **Scoped dynamic**: Granular loading per namespace and locale.       |
+
+## Strategy summary
+
+- **Static**: Simple; no network latency after the initial load. Downside: large bundle size.
+- **Dynamic**: Reduces initial weight (lazy-loading). Ideal when you have many locales.
+- **Scoped static**: Keeps code organized (logical separation) without complex extra network requests.
+- **Scoped dynamic**: Best approach for _code splitting_ and performance. Minimizes memory by loading only what the current view and active locale need.
+
+### What I measured:
+
+I ran the same multilingual app in a real browser for every stack, then wrote down what actually showed up on the wire and how long things took. Sizes are reported **after normal web compression**, because that is closer to what people download than raw source counts.
+
+- **Internationalization library size**: After bundling, tree-shaking and minification, the size of the i18n library is the size of the providers (e.g. `NextIntlClientProvider`) + hooks (e.g. `useTranslations`) code in an empty component. It does not include the loading of translation files. It answers how expensive the library is before your content enters the picture.
+
+- **JavaScript per page**: For each benchmark route, how much script the browser pulls in for that visit, averaged across the pages in the suite (and across locales where the report rolls them up). Heavy pages are slow pages.
+
+- **Leakage from other locales**: It's the content of the same page but in another language that would be loaded by mistake in the audited page. This content is unnecessary and should be avoided. (e.g. `/fr/about` page content in `/en/about` page bundle)
+
+- **Leakage from other routes**: The same idea for **other screens** in the app: whether their copy is riding along when you only opened one page. (e.g. `/en/about` page content in `/en/contact` page bundle). A high score hints at weak splitting or over-broad bundles.
+
+- **Average component bundle size**: Common UI pieces are measured **one at a time** instead of hiding inside one giant app number. It shows whether internationalization quietly inflates everyday components. For instance, if your component rerenders, it will load all that data from memory. Attaching a giant JSON to any component is like connecting a big store of unused data that will slow down your components’ performance.
+
+- **Language switch responsiveness**: I flip the language using the app’s own control and time how long it takes until the page has clearly switched, what a visitor would notice, not a lab micro-step.
+
+- **Rendering work after a language change**: A narrower follow-up: how much effort the interface took to repaint for the new language once the switch is in flight. Useful when the “felt” time and the framework cost diverge.
+
+- **Initial page load time**: From navigation to the browser considering the page fully loaded for the scenarios I tested. Good for comparing cold starts.
+
+- **Hydration time**: When the app exposes it, how long the client spends turning server HTML into something you can actually click. A dash in the tables means that implementation did not provide a reliable hydration figure in this benchmark.
+
+## Results in detail
+
+### 1 - Solutions to avoid
+
+Some solutions, such as `gt-next` or `lingo.dev`, are clearly best avoided. They combine vendor lock-in with polluting your codebase. Despite many hours trying to implement them, I never got them working on TanStack Start or Next.js.
+
+Issues encountered:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- For a 110kb app, `gt-next` adds more than 440kb extra.
+- `Quota Exceeded, please upgrade your plan` on the very first build with General Translation.
+- Translations are not rendered; I get the error `Error: <T> used on the client-side outside of <GTProvider>`, which seems to be a bug in the library.
+- While implementing **gt-next**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
+- The library blocks static rendering of Next.js pages.
+
+**(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
+
+- AI quota exceeded, blocking the build entirely, so you cannot ship to production without paying.
+- The compiler was missing almost 40% of the translated content. I had to rewrite all `.map` into flat component blocks to make it work.
+- Their CLI is buggy and used to reset the config file for no reason.
+- At build, it totally erased the generated JSONs when new content was added. As a result, a handful of keys could wipe out more than 300 existing keys.
+
+### 2 - Experimental solutions
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+The idea behind `Wuchale` is interesting but not yet viable. I hit reactivity issues and had to force rerendering of the provider to get the app working. The documentation is also fairly unclear, which makes onboarding harder.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` offers an innovative, well-thought-out approach. Even so, in this benchmark the advertised tree-shaking did not work for my Next.js or TanStack Start setups. The workflow and DX are more complex than other options.
+Personally I dislike having to regenerate JS files before every push, which creates constant merge conflict risk via PRs. The tool also seems more focused on Vite than on Next.js.
+Even if in theory the tree-shaking strategy works, it does include all locales in the bundle anyway. Paraglide offers no way to lazy-load the content. That means your page size grows in line with the number of locales you have.
+Finally, in comparison with other solutions, Paraglide does not use a store (e.g. React context) to retrieve the current locale to render the content. For each node parsed, it will request the locale from the localStorage / cookie etc. It leads to execution of unnecessary logic that impacts the component reactivity.
+
+### 3 - Acceptable solutions
+
+**(Tolgee)** (`@tolgee/react@7.0.0`):
+
+`Tolgee` addresses many of the issues mentioned earlier. I found it harder to adopt than similar tools. It does not provide type safety, which also makes catching missing keys at compile time harder. I had to wrap Tolgee’s functions with my own to add missing-key detection.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` is the trendiest option and the one AI agents push most, but in my view wrongly so. Getting started is easy. In practice, optimizing to limit leakage is complex. Combining dynamic loading + namespacing + TypeScript types slows development a lot. The package is also fairly heavy (~13kb for `NextIntlClientProvider` + `useTranslations`, which is more than 2× `next-intlayer`). **next-intl** used to block static rendering of Next.js pages. It provides a helper named `setRequestLocale()`. That seems partially addressed for centralized files like `en.json` / `fr.json`, but static rendering still breaks when content is split into namespaces such as `en/shared.json` / `fr/shared.json` / `es/shared.json`.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` is probably the most popular option because it was among the first i18n solutions for JavaScript apps. It has many community plugins. It shares the same major downsides as `next-intl`. The package is especially heavy (~18kb for `I18nProvider` + `useTranslation`, about 3× `next-intlayer`).
+
+Message formats also differ: `next-intl` uses ICU MessageFormat, while `i18next` uses its own format.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` also tackles the issues above but does not differ much from `next-intl` or `next-i18next`. It includes `scopedT()` for namespace-specific translations, but using it has essentially no impact on bundle size.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` is often praised. Personally I found the `lingui extract` / `lingui compile` workflow more complex than alternatives, without a clear upside. I also noticed inconsistent syntaxes that confuse AIs (e.g. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+### 4 - Recommendations
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` is my main recommendation if you like a `t()`-style API. It is elegant via `next-translate-plugin`, loading namespaces through `getStaticProps` with a Webpack / Turbopack loader. It is also the lightest option here (~2.5kb). For namespacing, defining namespaces per page or route in config is well thought out and easier to maintain than main alternatives like **next-intl** or **next-i18next**. In version `3.1.2`, I noted that static rendering did not work; Next.js fell back to dynamic rendering.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+I will not personally judge `next-intlayer` for objectivity’s sake, since it is my own solution.
+
+### Personal note
+
+This note is personal and does not affect the benchmark results. In the i18n world you often see consensus around `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>`.
+
+In React apps, injecting a function as a `ReactNode` is, in my view, an anti-pattern. It also adds avoidable complexity and JavaScript execution overhead (even if barely noticeable).