@intlayer/docs 9.5.3 → 9.5.4-canary.0

package/blog/en/___per-component_vs_centralized_i18n.md

@@ -1,255 +0,0 @@
----
-createdAt: 2025-09-10
-updatedAt: 2025-09-10
-title: "Per-Component vs. Centralized i18n: A New Approach with Intlayer"
-description: A deep dive into internationalization strategies in React, comparing centralized, per-key, and per-component approaches, and introducing Intlayer.
-keywords:
-  - i18n
-  - React
-  - Internationalization
-  - Intlayer
-  - Optimization
-  - Bundle Size
-slugs:
-  - blog
-  - per-component-vs-centralized-i18n
-author:
-  name: Aymeric PINEAU
-  github: aymericzip
----
-
-# Per-Component vs. Centralized i18n
-
-I'm the creator of Intlayer, an i18n solution that takes a **per-component approach**.
-
-The per-component approach isn't exactly new.
-On the Vue side, `vue-i18n` has a ['Single File Components'](https://vue-i18n.intlify.dev/guide/advanced/sfc.html) approach.It also exists in Nuxt with per-component translations [here](https://i18n.nuxtjs.org/docs/guide/per-component-translations).
-
-Even in a Flutter app, we can often find this pattern:
-
-```bash
-lib/
-├── features/
-│   ├── login/
-│   │   ├── login_screen.dart
-│   │   └── login_screen.i18n.dart  <- Translations live here
-
-```
-
-```dart
-import 'package:i18n_extension/i18n_extension.dart';
-
-extension Localization on String {
-  static var _t = Translations("en_us") +
-      {
-        "en_us": "Hello",
-        "pt_br": "Olá",
-        "es": "Hola",
-      };
-
-  String get i18n => localize(this, _t);
-}
-
-```
-
-However, in the React world, we mainly see different approaches, that I will group in three categories:
-
-1. **Centralized approach** (i18next, next-intl, react-intl, lingui)
-2. **Per-component approach** (Intlayer)
-3. **Per-key approach** (inlang)
-
-In this blog, I won't focus on compiler-based solutions, which I already covered here: [Compiler vs Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md).
-Note that compiler-based i18n (e.g., Lingui) simply automates the extraction and loading of content. Under the hood, they often share the same limitations as the centralized approach.
-
-So, what are the differences?
-
-- **A Centralized approach** (with no namespaces) considers a single source to retrieve content. By default, you load the content from all pages when your app loads.
-- **Per-component and Per-key approaches** fine-grain the content retrieval.
-
-> Note that the more you fine-grain how you retrieve your content, the more you risk inserting additional state and logic into your components.
-> For instance, a page can easily include 500 text nodes (`<p>`, `<span>`). A per-key approach will effectively insert 500 new component instances to handle the translation, each potentially using their own `useState`, `useEffect`, or `useContext`.
-
-Here is a visualization of the trade-off:
-
-```bash
-Count of useState / Overhead (100 blocks <p> / 10 components)
-100 | x Per-key
-    |
-    |
-    ...
-    |
-    |
-    |
-    |
- 10 |  x Per-component
-    |
-  1 |                                           x Centralized
-    |-------------------------------------------------------->
-    0                                          900     1000
-           % of unused content (Based on 10 unique pages)
-
-```
-
-In parallel, you should know that when you dynamically load your content (`await import()`), you end up with extra requests to your server. One extra `useState` or hook relates to one extra request to your server.
-
-> To fix this point, Intlayer suggests grouping multiple content definitions under a same key, Intlayer will then merge that content.
-
-### So why is the Centralized approach so popular?
-
-- First, i18next was the first solution to become widely used, following an approach inspired by PHP and Java, which rely on a clear separation of concerns (MVP). i18next arrive even before the trend of frontend frameworks and component based architecture.
-- Then, once a library is widely adopted, it becomes difficult to shift the ecosystem to other patterns.
-- Using a centralized approach also makes things easier in Translation Management Systems such as Crowdin, Phrase, or Localized.
-- The logic behind a per-component approach is more complex than a centralized one and takes extra time to develop, especially when you have to solve problems like identifying where the content is located.
-
-### Okay, but why not just stick to a Centralized approach?
-
-Let me tell you why it can be problematic for your app:
-
-- **Unused Data:** When a page loads, you often load the content from all other pages. (In a 10-page app, that's 90% unused content loaded). You lazy load a modal? The i18n library doesn't care, it loads the strings first anyway.
-- **Performance:** For each re-render, every single one of your components is hydrated with a massive JSON payload, which impacts your app's reactivity as it grows.
-- **Maintenance:** Maintaining large JSON files is painful. You have to jump across files to insert a translation, ensuring no translations are missing and no **orphan keys** are left behind.
-- **Design-system:** It creates incompatibility with design systems (e.g., a `LoginForm` component) and constrains component duplication across different apps.
-
-**"But we invented Namespaces!"**
-
-Sure, and that's an massive move forward. Let's look at the comparison of the main bundle size of a Vite + React + React Router v7 + Intlayer setup. We simulated a 20-page application.
-
-The first example does not include lazy-loaded translations per locale and no namespace splitting. The second includes content purging + dynamic loading for translations.
-
-| Optimized bundle                                                                                      | Bundle not optimized                                                                                                     |
-| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| ![optimized bundle](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true) | ![no optimized bundle](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle_no_optimization.png?raw=true) |
-
-So thanks for namespaces, we moved from this structure:
-
-```bash
-locale/
-├── en.json
-├── fr.json
-├── es.json
-
-```
-
-To this one:
-
-```bash
-locale/
-├── en/
-│   ├── common.json
-│   ├── navbar.json
-│   ├── footer.json
-│   ├── home.json
-│   ├── about.json
-├── fr/
-│   ├── ...
-├── es/
-│   ├── ...
-
-```
-
-Now you have to finely manage what part of your app content should be loaded, and where. Conclusion, 90% of projects just skip this part due to the complexity (see [next-i18next guide](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_using_next-i18next.md) for instance to see the challenges that represents (just) following good practices).
-Consequently, 95% of projects end up with the massive JSON loading problem explained earlier.
-
-However, not all per-component approaches solve this. For instance, `vue-i18n`'s approach does not inherently lazy load the translations, so you face the same bundle issues.
-Moreover, without proper separation of concerns, it becomes much more difficult to extract and provide your translations to translators for review.
-
-### How Intlayer's per-component approach solves this
-
-Intlayer proceeds in several steps:
-
-1. **Declaration:** Declare your content anywhere in your codebase using `.content.{ts|jsx|cjs|json|json5|...}` files. This ensures separation of concerns while keeping content colocated. A content file can be per-locale or multilingual.
-2. **Processing:** Intlayer runs a build step to process JS logic, handle missing translation fallbacks, generate TypeScript types, manage duplicated content, and fetch content from your CMS, and more.
-3. **Purging:** When your app builds, Intlayer purges unused content (a bit like how Tailwind manages your classes) by replacing the content as follows:
-
-**Declaration:**
-
-```tsx
-// src/MyComponent.tsx
-export const MyComponent = () => {
-  const content = useIntlayer("my-key");
-  return <h1>{content.title}</h1>;
-};
-```
-
-```tsx
-// src/myComponent.content.ts
-export const {
-  key: "my-key",
-  content: t({
-    en: { title: "My title" },
-    fr: { title: "Mon titre" }
-  })
-}
-
-```
-
-**Processing:** Intlayer builds the dictionary based on the `.content` file and generates:
-
-```json5
-// .intlayer/dynamic_dictionary/en/my-key.json
-{
-  "key": "my-key",
-  "content": { "title": "My title" },
-}
-```
-
-**Replacement:** intlayer extracts your component during the application build.
-
-**- Static Import Mode:**
-
-```tsx
-// Representation of the component in JSX-like syntax
-export const MyComponent = () => {
-  const content = useDictionary({
-    key: "my-key",
-    content: {
-      nodeType: "translation",
-      translation: {
-        en: { title: "My title" },
-        fr: { title: "Mon titre" },
-      },
-    },
-  });
-
-  return <h1>{content.title}</h1>;
-};
-```
-
-**- Dynamic Import Mode:**
-
-```tsx
-// Representation of the component in JSX-like syntax
-export const MyComponent = () => {
-  const content = useDictionaryAsync({
-    en: () =>
-      import(".intlayer/dynamic_dictionary/en/my-key.json", {
-        with: { type: "json" },
-      }).then((mod) => mod.default),
-    // Same for other languages
-  });
-
-  return <h1>{content.title}</h1>;
-};
-```
-
-> `useDictionaryAsync` uses a Suspense-like mechanism to load the localized JSON only when needed.
-
-**Key benefits of this per-component approach:**
-
-- Keeping your content declaration close to your components allows better maintainability (e.g moving a components to another app or design system. Deleting the component folder remove the related content too, as you probably already do for your `.test`, `.stories`)
-
-- A per-component approach prevents AI agents from needing to jump across all your different files. It treats all translations in one place, limiting the complexity of the task, and the amount of tokens used.
-
-### Limitations
-
-Of course, this approach comes with trade-offs:
-
-- It is harder to connect to other l10n systems and extra tooling.
-- You get locked in (which is basically already the case with any i18n solution due to their specific syntax).
-
-That's the reason why Intlayer tries to provide a complete toolset for i18n (100% free and OSS), including AI translation using your own AI Provider and API keys. Intlayer also provides tooling to synchronize your JSON, functioning like ICU / vue-i18n / i18next message formatters to map the content to their specific formats.
-
----
-
-Is it overkill? Or will it become the next Tailwind for content?
-I'm happy to take your honest feedback about it. Your objections really help me build a better product.

package/blog/pl/___per-component_vs_centralized_i18n.md

@@ -1,100 +0,0 @@
----
-createdAt: 2025-09-10
-updatedAt: 2025-09-10
-title: "Per-Component vs. Centralized i18n: Nowe podejście z Intlayer"
-description: Dogłębne porównanie strategii internacjonalizacji w React, porównanie podejść scentralizowanych, per-key i per-component, oraz wprowadzenie Intlayer.
-keywords:
-  - i18n
-  - React
-  - Internationalization
-  - Intlayer
-  - Optimization
-  - Bundle Size
-slugs:
-  - blog
-  - per-component-vs-centralized-i18n
-author:
-  name: Aymeric PINEAU
-  github: aymericzip
----
-
-# Per-Component vs. Centralized i18n
-
-Jestem twórcą Intlayer, rozwiązania i18n, które przyjmuje **podejście per-component**.
-
-Podejście per-component nie jest dokładnie nowe.
-Po stronie Vue, `vue-i18n` ma podejście ['Single File Components'](https://vue-i18n.intlify.dev/guide/advanced/sfc.html). Istnieje również w Nuxt z tłumaczeniami per-component [tutaj](https://i18n.nuxtjs.org/docs/guide/per-component-translations).
-
-Nawet w aplikacji Flutter możemy często znaleźć ten wzorzec:
-
-```bash
-lib/
-├── features/
-│   ├── login/
-│   │   ├── login_screen.dart
-│   │   └── login_screen.i18n.dart  <- Tłumaczenia żyją tutaj
-
-```
-
-```dart
-import 'package:i18n_extension/i18n_extension.dart';
-
-extension Localization on String {
-  static var _t = Translations("en_us") +
-      {
-        "en_us": "Hello",
-        "pt_br": "Olá",
-        "es": "Hola",
-      };
-
-  String get i18n => localize(this, _t);
-}
-
-```
-
-Niemniej jednak, w świecie React, głównie widzimy różne podejścia, które pogrupuję w trzy kategorie:
-
-1. **Podejście scentralizowane** (i18next, next-intl, react-intl, lingui)
-2. **Podejście per-component** (Intlayer)
-3. **Podejście per-key** (inlang)
-
-W tym blogu nie będę skupiać się na rozwiązaniach bazujących na kompilatorze, które już omówiłem tutaj: [Compiler vs Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md).
-Zauważ, że compiler-based i18n (np. Lingui) po prostu automatyzuje ekstrakcję i ładowanie zawartości. Za kulisami, często dzielą te same ograniczenia co podejście scentralizowane.
-
-Co zatem są różnice?
-
-- **Podejście scentralizowane** (bez namespaces) rozważa pojedyncze źródło do pobierania zawartości. Domyślnie ładujesz zawartość wszystkich stron przy załadowaniu aplikacji.
-- **Podejścia per-component i per-key** drobniutko dzielą pobieranie zawartości.
-
-> Zauważ, że im bardziej dzielisz jak pobierasz zawartość, tym bardziej ryzykujesz wstawiać dodatkowy stan i logikę do komponentów.
-> Na przykład, strona może łatwo zawierać 500 węzłów tekstu (`<p>`, `<span>`). Podejście per-key efektywnie wstawi 500 nowych instancji komponentu aby obsłużyć tłumaczenie, każde potencjalnie używając własnego `useState`, `useEffect`, lub `useContext`.
-
-Tutaj jest wizualizacja kompromisu:
-
-```bash
-Count of useState / Overhead (100 blocks <p> / 10 components)
-100 | x Per-key
-    |
-    |
-    ...
-    |
-    |
-    |
-    |
- 10 |  x Per-component
-    |
-  1 |                                           x Centralized
-    |-------------------------------------------------------->
-    0                                          900     1000
-           % of unused content (Based on 10 unique pages)
-
-```
-
-Równolegle, powinieneś wiedzieć, że gdy dynamicznie ładujesz zawartość (`await import()`), skończysz z dodatkowymi żądaniami do serwera. Jedno dodatkowe `useState` lub hook odnosi się do jednego dodatkowego żądania do serwera.
-
-> Aby naprawić ten punkt, Intlayer sugeruje grupowanie wielu definicji zawartości pod tym samym kluczem, Intlayer będzie wtedy scalać tę zawartość.
-
-### Dlaczego zatem podejście scentralizowane jest tak popularne?
-
-- Najpierw, i18next była pierwszym rozwiązaniem, które stało się szeroko stosowane, podążając za podejściem inspirowanym PHP i Java, które opierają się na wyraźnej separacji obaw (MVP). i18next przybył nawet przed trendem frameworków frontendowych i architektury opartej na komponentach.
-- Następnie, gdy biblioteka jest szeroko przyjęta, trudno jest przesunąć ekosystem do innych wzorców.

package/docs/en/benchmark/___NOTE.md

@@ -1,101 +0,0 @@
----
-createdAt: 2024-03-07
-updatedAt: 2024-03-07
-title: Benchmark Notes
-description: Detailed notes and observations from the i18n framework benchmark.
-keywords:
-  - benchmark
-  - i18n
-  - notes
-  - comparison
-slugs:
-  - doc
-  - benchmark
-  - note
-author:
-  name: Aymeric PINEAU
-  github: aymericzip
----
-
-**gt-react** / **gt-next**
-
-I was not able to test gt-react / gt-next. The libraries are not functional and break the application.
-
-- I was not able to test the app reactivity.
-- 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.
-- This library requires a dependency on the General Translation server for translation. Even a single translation attempt returned an error: `Quota Exceeded, please upgrade your plan`. The risk of vendor lock-in is high.
-- These libraries use an anti-pattern through the `initializeGT()` function, blocking the bundle from tree-shaking cleanly.
-- For nextjs implementation, the library blocks static rendering of Next.js pages.
-
-**Lingo.dev**
-
-- Heavy dependency on the lingo.dev server to generate the translations. Even if they include a more generous free tier than General Translation, the risk of vendor lock-in is high.
-- The setup was not straightforward. I had to reverse engineer their code and force overwriting an environment variable to make it work.
-- Their CLI is buggy and used to rewrite the config file each time I used it.
-- The compiler was missing almost 40% of the translated content. I had to rewrite all `.map` into flat component blocks to make it work.
-- I met reactivity issues with the library. On locale change I had to force rerendering of the provider to make it work.
-- On rebuild it used to randomly remove all generated translations without any reason.
-
-**next-translate**
-
-- For Next.js applications, this library was a great discovery; the approach is extremely well thought out and easy to implement, and the results are impressive. The gain in comparison to other libraries using `t()` syntax is significant, such as **next-intl** or **next-i18next**.
-- This library uses a build transformation approach with `react-translate-plugin`: it rewrites your pages and inserts content retrieval using `getStaticProps` or `getServerSideProps` via a Webpack / Turbopack loader. The result is that you never fetch content from other locales.
-- 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**.
-- This library supports both Webpack and Turbopack, client and server components, and the Pages and App Router.
-- Even if that solution is >6 years old, the library is still actively maintained.
-- There is no website and no online documentation; they are only available on GitHub. I like finding great libraries and fixing problems in a clean way, without extra marketing layers.
-- All constants are transformed into functions, leading to an anti-pattern. Syntax such as `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` introduces unnecessary complexity and leads to JavaScript execution overhead.
-- The library blocks static rendering of Next.js pages.
-
-**Tolgee**
-
-- The implementation was difficult to get working, especially because the library does not provide type safety. To detect wrong keys, I had to manually rewrite the type-safety logic and reuse my own implementation of the `getTranslation` function.
-- This library supports both Webpack and Turbopack, client and server components, and the Pages and App Router.
-- There is no website and no online documentation; they are only available on GitHub.
-- On tanstack start I also met reactivity issues with the library. On locale change I had to force the rerendering of the provider to make it work. I had to subcribe to the locale change event to make it work when loading the page in another locale.
-- For nextjs implementation, the library blocks static rendering of Next.js pages.
-- I also met issues with the DevTools provided by the library. It used to log errors in the server side console.
-
-**next-translate**
-
-- Even if that solution is >6 years old, the library is still actively maintained.
-- This library uses a build transformation approach with `react-translate-plugin`: it rewrites your pages and inserts content retrieval using `getStaticProps` or `getServerSideProps`. The result is that you never fetch content from other locales.
-
-**next-intl** / **use-intl** / **next-i18next** / **react-i18next** / **next-international**
-
-- Same pros and cons for all these libraries that use a `t()` function syntax.
-- Optimizations are possible but extremely time consuming. Good practices are not clearly highlighted, and it may be easy for agents or junior developers to harm application performance through bad practices. Especially when using namespacing plus dynamic loading, maintaining type safety, and knowing exactly which namespace should be included on which page is a nightmare.
-- All these libraries offer a similar approach, well connected with the React reactivity system. But `next-intl` offers additional features, such as middleware support, formatters, etc.
-- The message formats diverge between libraries. `next-intl` uses the ICU MessageFormat format, while `i18next` uses its own format.
-- **next-intl** is a much lighter solution than **i18next**, but remains heavy and poorly optimized.
-- **next-intl** used to block static rendering of Next.js pages. It provides a fix function named `setRequestLocale()`, that was not easy to understand the cause of the issue or how to fix it. This issue seems to have been solved and no longer blocks static rendering for centralized content such as `en.json` / `fr.json` / `es.json` / etc. Note that it still blocks static rendering when content is scoped into namespaces such as `en/shared.json` / `fr/shared.json` / `es/shared.json` / etc.
-- Both solutions do not offer a way to translate synchronous server components such as design-system navbar, footer, etc. As a result, all components have to be translated on the client side.
-- All constants are transformed into functions, leading to an anti-pattern. Syntax such as `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` introduces unnecessary complexity and leads to JavaScript execution overhead.
-- **next-international** includes a custom `scopedT()` function that allows you to translate content in a specific namespace which make the refactoring process harder for optimization purpose. But because there is no way to split the jsons in namespaces, this function is quite useless. It only improves the DX, but has no impact on the bundle size.
-
-**Lingui**
-
-- Reasonable performance and impact, with good respect for best practices.
-- Implementation is complex for functions that are not page components, like in Next.js `generateMetadata`. You have to create a new i18n instance, pick the messages to load, then translate them.
-- The flow can be a bit complex to understand on first implementation.
-- Confusing syntax, e.g. `t()`, `t''`, `i18n.t()`, `<Trans>`. Knowing which practices to use in the application is not intuitive.
-
-**Wuchale**
-
-- Great approach trying to automate the extraction and translation process without any `t()` function syntax.
-- Svelte-first solution. The React adaptation of the library is not as mature as the Svelte version. The React application reactivity did not work. I had to force rerendering of the provider on locale change using a custom `isMounted()` state/effect to make it work.
-- Uses an anti-pattern for the initialization function to make it load before the router is initialized.
-
-**Paraglide**
-
-- Theoretically for applications including multiple locales, Paraglide includes all messages in the bundle. There is no way to dynamically load the messages. Even if they promote `tree-shaking` optimization, the library is mainly moving the bundling problem somewhere else. A future improvement for dynamic loading seems impossible given the library architecture. Using dynamic loading would lead to thousands of requests to the server.
-- In practice, the result using Paraglide is even worse then expected. On nextjs (Turbopack) as for tanstack start (Rolldown), the bundler does not even tree shake the messages. As a result, the final bundle size includes content from all pages and all locales.
-- Complex flow using JSON declaration files as the source of truth, plus generation of the message files at build time, then manual imports in each component.
-- All constants are transformed into functions, leading to an anti-pattern. Syntax such as `import * as m from '@/messages'` + `<>{m.myContent()}</>` introduces unnecessary complexity and leads to JavaScript execution overhead.
-- In comparison of other solution that use a react context to retrieve in a efficient way the current locale to render the content, Paraglide will read for each content node imported the locale from the localeStorage / cookie etc. It leads to execution of unnecessary logic.
-
-**react-intl**
-
-- Performant implementation, made by the Format.js team.
-- Confusing DX using the `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` introduces unnecessary complexity, leads to JavaScript execution overhead, and connect the global i18n instance to the all components node.

package/docs/en/benchmark/___nextjs.md

@@ -1,197 +0,0 @@
----
-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:
-  name: Aymeric PINEAU
-  github: aymericzip
-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:
-
-<ClickToOpenIframe
-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;"
-/>
-
-> [See complete benchmark data](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).