@intlayer/docs 9.5.6 → 9.5.7

package/blog/en/i18next_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "i18next vs Intlayer: 2026 Benchmark & Comparison"
 description: react-i18next and next-i18next measured against Intlayer on Next.js and TanStack Start. Bundle size, content leakage, locale-switch reactivity and developer experience.
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # i18next VS Intlayer | React & Next.js Internationalization (i18n) Benchmark
 
+![i18next VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `i18next` is the most widely used i18n framework in the JavaScript ecosystem. Through `react-i18next` and `next-i18next`, it powers a large share of React and Next.js applications. Intlayer is a compiler-based, component-scoped alternative.
 
 This article compares them on measurements rather than feature lists. The numbers come from [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), an open-source suite that builds the same application with each library and records what the browser actually downloads.
@@ -99,6 +101,10 @@ For each build, the suite records:
 
 ### Results on Next.js (`next-i18next`)
 
+Pick the metrics and the libraries you care about:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Library                           | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity | Hydration |
 | --------------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | --------: |
 | **base** (no i18n)                | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |   11.8 ms |
@@ -119,6 +125,15 @@ For each build, the suite records:
 - **Component size.** A component calling `useTranslation()` compiles to 26-79 KB depending on the setup; the same component with `useIntlayer()` compiles to 6.9 KB.
 - **Hydration** spikes to 27.7 ms in the `dynamic` setup: the i18next instance initializes and resolves its backend on the client before React can hydrate.
 
+<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;"
+/>
+
+> Full table, every library and every strategy, in the [Next.js benchmark report](https://intlayer.org/doc/benchmark/nextjs).
+
 ### Results on TanStack Start (`react-i18next`)
 
 Same test app on TanStack Start with plain `react-i18next`, which removes the Next.js-specific wiring from the comparison.
@@ -141,8 +156,19 @@ Same test app on TanStack Start with plain `react-i18next`, which removes the Ne
 - Intlayer's `static` row already has **0% page leakage** because only the dictionaries imported by the page's components are bundled. Enabling `importMode: 'dynamic'` removes the locale leakage too.
 - **Component size**: 24-27 KB per component with `react-i18next` versus 6-8 KB with Intlayer. `useTranslation()` binds every component to the global i18next instance.
 
+<ClickToOpenIframe
+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;"
+/>
+
+> Full table in the [TanStack Start benchmark report](https://intlayer.org/doc/benchmark/tanstack).
+
 ## Why the gap? Global instance vs. compiled dictionaries
 
+![Centralized catalogs versus per-component dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/assets/project_stucture_18n_vs_intlayer.png?raw=true)
+
 `i18next` was designed in 2012 as a runtime: a global instance holds a resource store, plugins extend it, and `t()` looks keys up at render time. This is what makes it so flexible (any framework, any backend, any format) and also what makes it costly:
 
 ```bash
@@ -166,7 +192,13 @@ Same test app on TanStack Start with plain `react-i18next`, which removes the Ne
                 └── page.tsx     # must know it needs ["common", "about"]
 ```
 
-The instance cannot know which keys a component will request, so it keeps whatever namespaces you tell it to load. Optimizing means **you** split catalogs into namespaces, **you** list the namespaces each page needs, and **you** keep that list correct as components move between pages. As the [benchmark notes](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md) put it: "maintaining type safety and knowing exactly which namespace should be included on which page is a nightmare".
+The instance cannot know which keys a component will request, so it keeps whatever namespaces you tell it to load. Optimizing means **you** split catalogs into namespaces, **you** list the namespaces each page needs, and **you** keep that list correct as components move between pages.
+
+The bill grows on two axes at once, pages and locales:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
+As the [benchmark notes](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md) put it: "maintaining type safety and knowing exactly which namespace should be included on which page is a nightmare".
 
 Intlayer removes the instance. Content is declared next to the component, and the compiler resolves the dependency graph at build time:
 
@@ -193,7 +225,8 @@ Intlayer removes the instance. Content is declared next to the component, and th
 
 ### Setup
 
-**next-i18next (App Router)**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-i18next" value="i18next">
 
 ```ts fileName="src/app/i18n/server.ts"
 import { createInstance } from "i18next";
@@ -228,7 +261,8 @@ export const initI18next = async (
 
 Plus a client-side `I18nProvider` that re-creates the instance with the same options, a `generateStaticParams`, and a `namespaces` list on every page.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -264,9 +298,13 @@ const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
 export default LocaleLayout;
 ```
 
+</Tab>
+</Tabs>
+
 ### Client component
 
-**react-i18next**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="react-i18next" value="i18next">
 
 ```json fileName="src/locales/en/about.json"
 {
@@ -304,7 +342,8 @@ export const Counter = () => {
 
 > The page rendering this component must load the `about` namespace, and `t("counter.label")` is a plain string until you augment `CustomTypeOptions`.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -345,9 +384,13 @@ export const Counter = () => {
 
 `label` and `increment` are typed; a typo is a TypeScript error, a missing French value is a build error.
 
+</Tab>
+</Tabs>
+
 ### Synchronous server component
 
-**next-i18next**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-i18next" value="i18next">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -366,7 +409,8 @@ export const ServerCounter = ({ t, locale, count }: ServerCounterProps) => (
 
 The page calls `i18n.getFixedT(locale, "about")` and threads `t` and `locale` down as props.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -385,6 +429,9 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## Keep the i18next API, get Intlayer's output
 
 You don't have to rewrite components to get the benchmark numbers above. `@intlayer/i18next`, `@intlayer/react-i18next` and `@intlayer/next-i18next` are drop-in adapters: `useTranslation`, `t()`, `<Trans>`, `{{interpolation}}`, `_one` / `_other` plurals, context suffixes and `returnObjects` keep working, served from Intlayer dictionaries compiled by the Intlayer compiler.
@@ -415,18 +462,85 @@ See the migration guides: [i18next](https://intlayer.org/doc/migration/i18next),
 
 ## When to choose which?
 
-- **Choose i18next** if you need its plugin ecosystem (detectors, backends, ICU, Locize), you localize outside React too (Node services, vanilla JS, other frameworks), your team already knows it, or a translation platform expects `locales/{lng}/{ns}.json`. Budget the time to namespace catalogs, wire a backend and maintain the page-to-namespace map if performance matters.
-- **Choose Intlayer** if you want **component-scoped content**, **strict TypeScript**, **build-time missing-key errors**, **zero-effort tree-shaking and lazy loading**, instant locale switching, synchronous server components, and built-in editorial tooling (Visual Editor, CMS, AI translation, MCP server). Especially relevant for large, modular codebases and design systems.
-- **Choose the `@intlayer/*-i18next` adapters** if you are already on i18next and want the bundle and reactivity gains without a rewrite.
+<AccordionGroup>
+<Accordion header="Choose i18next">
+
+You need its plugin ecosystem (detectors, backends, ICU, Locize), you localize outside React too (Node services, vanilla JS, other frameworks), your team already knows it, or a translation platform expects `locales/{lng}/{ns}.json`. Budget the time to namespace catalogs, wire a backend and maintain the page-to-namespace map if performance matters.
+
+</Accordion>
+<Accordion header="Choose Intlayer">
+
+You want **component-scoped content**, **strict TypeScript**, **build-time missing-key errors**, **zero-effort tree-shaking and lazy loading**, instant locale switching, synchronous server components, and built-in editorial tooling ([Visual Editor](https://intlayer.org/doc/concept/editor), [CMS](https://intlayer.org/doc/concept/cms), [AI translation](https://intlayer.org/doc/concept/auto-fill), [MCP server](https://intlayer.org/doc/mcp-server)). Especially relevant for large, modular codebases and design systems.
+
+</Accordion>
+<Accordion header="Choose the @intlayer/*-i18next adapters">
+
+You are already on i18next and want the bundle and reactivity gains without a rewrite. Your `locales/{lng}/{ns}.json` files stay the source of truth. Measured side by side in [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Why is i18next so much heavier than the other libraries?">
+
+It was designed as a framework-agnostic runtime: a global instance, a plugin pipeline, a resource store, a key resolver. That flexibility is compiled into every bundle. An empty component that only imports the library costs **19.7 KB gzip** with `next-i18next` against **5.5 KB** with `next-intlayer`, and the cost is paid on every page whatever your content weighs.
+
+</Question>
+
+<Question title="Does lazy loading with a backend fix it?">
+
+It fixes the bytes, not the latency. Moving to `i18next-resources-to-backend` saves ~49 KB per page but puts a network round-trip on the locale switch: **123 ms** in the `dynamic` setup and **185 ms** in `scoped-static`, against **3-4 ms** with Intlayer. Hydration also jumps to 27.7 ms because the instance resolves its backend before React can hydrate.
+
+</Question>
+
+<Question title="Can I reach 0% leakage with i18next?">
+
+Yes, with `scoped-dynamic`: one namespace per route, a resources backend and a page-to-namespace map you maintain by hand. It lands at 163.4 KB per page on Next.js, still **+22 KB** over Intlayer's 141.3 KB, which needed no configuration. See [bundle optimization](https://intlayer.org/doc/concept/bundle-optimization).
+
+</Question>
+
+<Question title="Do I have to rewrite my components to migrate?">
+
+No. `@intlayer/i18next`, `@intlayer/react-i18next` and `@intlayer/next-i18next` keep `useTranslation`, `t()`, `<Trans>`, `{{interpolation}}`, `_one` / `_other` plurals, context suffixes and `returnObjects`. One plugin line in `next.config.ts` or `vite.config.ts`. Step by step in the [next-i18next migration guide](https://intlayer.org/doc/migration/next-i18next).
+
+</Question>
+
+<Question title="What happens to my i18next plugins?">
+
+Backends and language detectors are accepted but inert: there is nothing left to load or detect at runtime. Locale detection becomes Intlayer's routing config (URL prefix, cookie, header). If your app fetches translations from a CMS at request time, use the [Intlayer CMS](https://intlayer.org/doc/concept/cms) or `intlayer pull` / `push` instead.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (same benchmark)
-- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer) (same benchmark)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (same benchmark)
+Same benchmark, other libraries:
+
+- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer)
+- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark)
 - [next-i18next vs next-intl vs Intlayer](https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer)
 - [react-i18next vs react-intl vs Intlayer](https://intlayer.org/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Going further on i18next:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next), the adapters measured on the same app
 - [Is i18next outdated?](https://intlayer.org/blog/is-i18next-outdated)
+- [Using Intlayer with i18next](https://intlayer.org/blog/intlayer-with-i18next) and [with react-i18next](https://intlayer.org/blog/intlayer-with-react-i18next)
+- [How to internationalize a Next.js app with next-i18next](https://intlayer.org/blog/nextjs-internationalization-using-next-i18next)
+
+Reference docs:
+
+- [Next.js benchmark report](https://intlayer.org/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/doc/benchmark/tanstack)
+- Compat adapters: [i18next](https://intlayer.org/doc/compatibility/i18next), [react-i18next](https://intlayer.org/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/doc/compatibility/next-i18next)
+- Migration guides: [i18next](https://intlayer.org/doc/migration/i18next), [react-i18next](https://intlayer.org/doc/migration/react-i18next), [next-i18next](https://intlayer.org/doc/migration/next-i18next)
+- [Bundle optimization](https://intlayer.org/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/doc/compiler)
+- [Per-component vs centralized i18n](https://intlayer.org/blog/per-component-vs-centralized-i18n)
+- [Compiler-driven vs declarative i18n](https://intlayer.org/blog/compiler-vs-declarative-i18n)
 
 ## GitHub STARs
 

package/blog/en/lingui_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "Lingui vs Intlayer: 2026 Benchmark & Comparison"
 description: Two compiler-based i18n libraries measured on Next.js and TanStack Start. Bundle size, content leakage, component size, hydration, locale-switch reactivity and developer experience.
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # Lingui VS Intlayer | React & Next.js Internationalization (i18n) Benchmark
 
+![JavaScript i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 Lingui and Intlayer are the two libraries in this benchmark that rely on a **compiler** rather than a pure runtime. Lingui extracts messages from macros at build time and compiles catalogs per locale. Intlayer compiles per-component dictionaries and tree-shakes them per locale. On paper they should be close. The numbers show where they diverge.
 
 The data comes from [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), an open-source suite that builds the same application with each library and records what the browser actually downloads and executes.
@@ -96,6 +98,10 @@ For each build, the suite records:
 
 ### Results on Next.js
 
+Pick the metrics and the libraries you care about:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Library             | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity | Hydration |
 | ------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | --------: |
 | **base** (no i18n)  | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |   11.8 ms |
@@ -114,6 +120,15 @@ For each build, the suite records:
 - **The source-locale fallback leaks.** Even in the optimized setups, **3-15% of `en` strings ship inside `fr` pages**. Lingui macros keep the source message available as a fallback, so it lands in the bundle next to the translation. Intlayer resolves fallbacks at build time and ships only the active locale.
 - **Component size explodes in `scoped-dynamic`.** Each component compiled in isolation averages **152.6 KB**, because every route's catalog is reachable from the component that imports it. The same component with `useIntlayer()` averages **6.9 KB**.
 
+<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;"
+/>
+
+> Full table, every library and every strategy, in the [Next.js benchmark report](https://intlayer.org/doc/benchmark/nextjs).
+
 ### Results on TanStack Start
 
 | Library                     | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity | Hydration |
@@ -135,8 +150,19 @@ For each build, the suite records:
 - **Intlayer's `static` row already has 0% page leakage** because only the dictionaries imported by the page's components are bundled. One line of config (`importMode: 'dynamic'`) removes the locale leakage too.
 - **`@intlayer/lingui`** keeps Lingui's macro syntax and serves it from Intlayer dictionaries. It trades some page size (137 KB, since the macro runtime stays) for smaller components (12.8 KB) and faster hydration than native Lingui. It's a migration step, not the destination.
 
+<ClickToOpenIframe
+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;"
+/>
+
+> Full table in the [TanStack Start benchmark report](https://intlayer.org/doc/benchmark/tanstack).
+
 ## Why the gap? Two compilers, two units of work
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Both libraries compile. The difference is **what** they compile.
 
 **Lingui compiles catalogs.** Macros in your source are extracted into a `.po` file per locale, then compiled into a JS module per locale. The unit is the **locale**. Splitting further, by route or by component, means creating multiple catalogs, configuring `lingui.config.ts` to extract each one from a different set of files, and loading the right one in each route. The runtime `I18n` instance is global; every `useLingui()` call subscribes the component to it.
@@ -176,7 +202,9 @@ Both libraries compile. The difference is **what** they compile.
             └── about.content.ts
 ```
 
-That's why the `scoped-dynamic` pattern is a build output for Intlayer and a configuration project for Lingui.
+That's why the `scoped-dynamic` pattern is a build output for Intlayer and a configuration project for Lingui. The gap widens on two axes at once, pages and locales:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 > To get the `dynamic` row's numbers, set `dictionary.importMode: 'dynamic'` in `intlayer.config.ts`. See the [bundle optimization doc](https://intlayer.org/doc/concept/bundle-optimization).
 
@@ -184,7 +212,8 @@ That's why the `scoped-dynamic` pattern is a build output for Intlayer and a con
 
 ### Setup
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="lingui.config.ts"
 import { defineConfig } from "@lingui/cli";
@@ -215,7 +244,8 @@ export const loadCatalog = async (locale: string) => {
 
 Then add `@lingui/babel-plugin-lingui-macro` (or `@lingui/swc-plugin`) to the bundler, run `lingui extract` after editing source, `lingui compile` before building, and wrap the tree in `<I18nProvider i18n={i18n}>`.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -232,9 +262,13 @@ export default config;
 
 Add `intlayer()` to `vite.config.ts` (or `withIntlayer()` to `next.config.ts`) and wrap the tree in `<IntlayerProvider>`. No extract or compile step: dictionaries are built when the bundler runs.
 
+</Tab>
+</Tabs>
+
 ### Component
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```tsx fileName="src/components/Counter.tsx"
 import { useState } from "react";
@@ -258,7 +292,8 @@ export const Counter = () => {
 
 The English text lives in the component; the French one lives in `src/locales/fr/messages.po` under a hashed ID, after `lingui extract` has run. Forgetting to run it, or to `compile`, silently falls back to English.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -297,11 +332,15 @@ export const Counter = () => {
 
 Both locales sit in one file next to the component. A missing `fr` value is a build error, a wrong key is a TypeScript error.
 
+</Tab>
+</Tabs>
+
 ### Outside of components
 
 Metadata, loaders, server functions: anywhere without a React tree.
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { setupI18n } from "@lingui/core";
@@ -324,7 +363,8 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 
 A fresh `I18n` instance per call, the right catalog loaded by hand, and `msg` + `i18n._()` instead of `t`. As the [benchmark notes](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md) put it, knowing when to use `t`, `` t` ` ``, `i18n.t()`, `msg` or `<Trans>` "is not intuitive".
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { getIntlayer } from "intlayer";
@@ -336,6 +376,9 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## Keep the Lingui macros, get Intlayer dictionaries
 
 `@intlayer/lingui` is a drop-in adapter for `@lingui/core` and `@lingui/react`. Macros keep compiling as before; the runtime `i18n._()` they compile to is served from Intlayer dictionaries, with `.po` sync plugins keeping your existing catalogs as a source of truth. ICU plurals and selects render identically.
@@ -353,16 +396,82 @@ Keep `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` in the build, ru
 
 ## When to choose which?
 
-- **Choose Lingui** if you want **ICU MessageFormat** with typed macros, your translators work in **`.po`** with an existing TMS pipeline, you prefer source strings inline in JSX, and your team is fine owning the extract / compile / catalog-splitting workflow. Its per-page JS is competitive once lazy loading is set up.
-- **Choose Intlayer** if you want **component-scoped content**, **strict TypeScript**, **build-time missing-key errors**, **zero-effort tree-shaking and lazy loading**, small components, fast hydration, instant locale switching, and built-in editorial tooling (Visual Editor, CMS, AI translation, MCP server). Especially relevant for large, modular codebases and design systems.
-- **Choose `@intlayer/lingui`** if you are on Lingui and want to move to Intlayer dictionaries incrementally without touching macros.
+<AccordionGroup>
+<Accordion header="Choose Lingui">
+
+You want **ICU MessageFormat** with typed macros, your translators work in **`.po`** with an existing TMS pipeline, you prefer source strings inline in JSX, and your team is fine owning the extract / compile / catalog-splitting workflow. Its per-page JS is competitive once lazy loading is set up.
+
+</Accordion>
+<Accordion header="Choose Intlayer">
+
+You want **component-scoped content**, **strict TypeScript**, **build-time missing-key errors**, **zero-effort tree-shaking and lazy loading**, small components, fast hydration, instant locale switching, and built-in editorial tooling ([Visual Editor](https://intlayer.org/doc/concept/editor), [CMS](https://intlayer.org/doc/concept/cms), [AI translation](https://intlayer.org/doc/concept/auto-fill), [MCP server](https://intlayer.org/doc/mcp-server)). Especially relevant for large, modular codebases and design systems.
+
+</Accordion>
+<Accordion header="Choose @intlayer/lingui">
+
+You are on Lingui and want to move to Intlayer dictionaries incrementally without touching macros. Your `.po` catalogs stay the source of truth through the [PO sync plugin](https://intlayer.org/doc/compatibility/lingui). Measured side by side in [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Lingui also compiles. Why is the output so different?">
+
+Because the unit of compilation differs. Lingui compiles **one catalog per locale**: everything below that, per-route catalogs, lazy loading, keeping the fallback out of the bundle, is configuration. Intlayer compiles **one dictionary per component**, so route scoping falls out of the build. That is why a Lingui component compiled in isolation weighs 58-153 KB against 6-8 KB.
+
+</Question>
+
+<Question title="Why does locale leakage never reach 0% with Lingui?">
+
+Macros keep the source message available as a runtime fallback, so the English string ships next to its translation. The benchmark measures **3-15% of `en` strings inside `fr` pages** in every optimized setup. Intlayer resolves fallbacks at build time and ships only the active locale.
+
+</Question>
+
+<Question title="Is Lingui's per-page JavaScript really competitive?">
+
+Yes, and on TanStack Start it wins by a hair: 115.2 KB in `dynamic` against 118.6 KB for Intlayer. Compiled catalogs with hashed IDs are compact. The cost shows up elsewhere: hydration at 28-34 ms against 11-14 ms, and a **42 ms** locale switch in the `scoped-dynamic` setup, where the route catalog is fetched, loaded and activated before the switch is visible.
+
+</Question>
+
+<Question title="Do I have to give up macros to migrate?">
+
+No. `@intlayer/lingui` keeps `` t`...` ``, `<Trans>`, `msg`, `plural`, `select` and `selectOrdinal` compiling as before; only what `i18n._()` resolves against changes. Keep `@lingui/babel-plugin-lingui-macro` or `@lingui/swc-plugin` in the build, running before the Intlayer compiler. See the [Lingui compatibility doc](https://intlayer.org/doc/compatibility/lingui).
+
+</Question>
+
+<Question title="What about the extract and compile steps?">
+
+They stay for the macros, and they go away for Intlayer's own content. `.content.ts` dictionaries are built when the bundler runs, with no separate CLI pass, and [`intlayer test`](https://intlayer.org/doc/concept/cli) fails CI on a missing key instead of silently falling back to the source string.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (same benchmark)
-- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer) (same benchmark)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (same benchmark)
-- [Compiler vs declarative i18n](https://intlayer.org/blog/compiler-vs-declarative-i18n)
+Same benchmark, other libraries:
+
+- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Going further:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui), the adapter measured on the same app
+- [Compiler-driven vs declarative i18n](https://intlayer.org/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/blog/icu-message-format)
+
+Reference docs:
+
+- [Next.js benchmark report](https://intlayer.org/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/doc/compatibility/lingui)
+- [Bundle optimization](https://intlayer.org/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/doc/compiler)
 
 ## GitHub STARs