@intlayer/docs 9.5.6 → 9.5.8

package/blog/en-GB/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 Internationalisation (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 catalogues 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 optimised 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 catalogue 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/en-GB/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/en-GB/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 catalogues.** 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 catalogues, 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 optimisation doc](https://intlayer.org/en-GB/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,12 @@ 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 +291,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 +331,14 @@ 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 +361,8 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 
 A fresh `I18n` instance per call, the right catalogue 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 +374,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 catalogues as a source of truth. ICU plurals and selects render identically.
@@ -353,16 +394,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 / catalogue-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/en-GB/doc/concept/editor), [CMS](https://intlayer.org/en-GB/doc/concept/cms), [AI translation](https://intlayer.org/en-GB/doc/concept/auto-fill), [MCP server](https://intlayer.org/en-GB/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/en-GB/doc/compatibility/lingui). Measured side by side in [Lingui vs @intlayer/lingui](https://intlayer.org/en-GB/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/en-GB/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/en-GB/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/en-GB/blog/next-intl-vs-intlayer) (same benchmark)
-- [i18next vs Intlayer](https://intlayer.org/en-GB/blog/i18next-vs-intlayer) (same benchmark)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/en-GB/blog/vue-i18n-vs-intlayer-benchmark) (same benchmark)
-- [Compiler vs declarative i18n](https://intlayer.org/en-GB/blog/compiler-vs-declarative-i18n)
+Same benchmark, other libraries:
+
+- [next-intl vs Intlayer](https://intlayer.org/en-GB/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/en-GB/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/en-GB/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/en-GB/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/en-GB/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Going further:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/en-GB/blog/lingui-vs-intlayer-lingui), the adapter measured on the same app
+- [Compiler-driven vs declarative i18n](https://intlayer.org/en-GB/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/en-GB/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/en-GB/blog/icu-message-format)
+
+Reference docs:
+
+- [Next.js benchmark report](https://intlayer.org/en-GB/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/en-GB/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/en-GB/doc/compatibility/lingui)
+- [Bundle optimization](https://intlayer.org/en-GB/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/en-GB/doc/compiler)
 
 ## GitHub STARs
 

package/blog/en-GB/next-intl_vs_intlayer-next-intl.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs @intlayer/next-intl: Same API, Different Bundle"
 description: What changes when the next-intl imports of a Next.js app are served by the @intlayer/next-intl compat adapter. Bundle size, leakage, component size and hydration measured on the same code, plus what the adapter keeps, ignores and cannot replace.
 keywords:
@@ -26,6 +26,8 @@ author: aymericzip
 
 # next-intl VS @intlayer/next-intl | Same API, Different Bundle
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/next-intl` is a compat adapter: it exposes the `next-intl` API (`useTranslations`, `getTranslations`, `useLocale`, `t.rich()`, ICU plurals, `NextIntlClientProvider`...) and serves it from dictionaries compiled by Intlayer. The application code does not change. The bundle does.
 
 This article compares the two on the same Next.js application, built once with `next-intl` and once with the adapter. The numbers come from [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), an open-source suite that records what the browser actually downloads. If you want the `next-intl` vs Intlayer comparison as libraries, read [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer). This one is about what the adapter changes when you keep your components as they are.
@@ -109,6 +111,10 @@ For each build, the suite records:
 
 ### Results on Next.js
 
+Pick the metrics and the libraries you care about:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Setup                     | 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 |
@@ -129,6 +135,15 @@ For each build, the suite records:
 - **Hydration is 2 ms faster** (12.8 vs 14.7 ms): there is no message object to deserialise from the RSC payload before React can hydrate.
 - **The adapter is not the native runtime.** `next-intlayer` sits at **141.3 KB**, +0.3 KB over the base app, with a 5.5 KB runtime. The adapter carries the `next-intl` API surface (`useFormatter`, `t.rich`, the ICU resolver) on top of Intlayer's core, hence 8.0 KB and +6 KB per page. It is the bridge, not the destination.
 
+<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/en-GB/doc/benchmark/nextjs).
+
 ### Results on TanStack Start (`use-intl`)
 
 `use-intl` is the framework-agnostic core of `next-intl`. Its adapter, `@intlayer/use-intl`, follows the same design with a Vite plugin (`@intlayer/use-intl/plugin`).
@@ -152,11 +167,24 @@ For each build, the suite records:
 - **Locale switching is faster.** The optimised `use-intl` setups take **13-21 ms** to update `html[lang]`; the adapter takes **4-9 ms**. Fewer components re-render, and nothing is re-picked from a message tree.
 - **`static` keeps every locale.** The adapter's `static` row shows 49.7% locale leakage, the same as native Intlayer in `static` mode: all locales are bundled, only the page's dictionaries are. One line of config (`importMode: 'dynamic'`) removes it.
 
+<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/en-GB/doc/benchmark/tanstack).
+
 ## Why the numbers move
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Nothing in the component changed, so the gains come entirely from what `useTranslations` is bound to.
 
-**With `next-intl`**, the binding is the provider. `NextIntlClientProvider` receives the whole `messages` object for the locale; every `useTranslations("about")` reads from it. The bundler sees one component importing one hook that reads one context, and cannot know that only the `about` branch is used. The routes below all share the same message object, so the page-leak column reads ~90% until you split the file yourself.
+**With `next-intl`**, the binding is the provider. `NextIntlClientProvider` receives the whole `messages` object for the locale; every `useTranslations("about")` reads from it. The bundler sees one component importing one hook that reads one context, and cannot know that only the `about` branch is used. The routes below all share the same message object, so the page-leak column reads ~90% until you split the file yourself, and the waste grows on two axes, pages and locales:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -280,25 +308,106 @@ export default withIntlayer(nextConfig);
 
 ## Limits to know before you start
 
-- **Routing config moves to `intlayer.config.ts`.** `createNavigation(routing)` and `createMiddleware(routing)` keep their signature but ignore the argument: locales, default locale and prefix strategy come from Intlayer's `routing` config. If you use `next-intl`'s localised `pathnames` (`/about` → `/a-propos`), the adapter does not interpolate them; Intlayer's `routing.rewrite` covers that case but it is a separate change.
-- **Namespace-less `useTranslations()` is not bound.** The optimise pass needs a static namespace to know which dictionary to import. A bare call still works, through a runtime registry that references every dictionary, which is exactly the leakage you were trying to remove. Pass the namespace.
-- **The adapter is not free.** 8.0 KB of runtime versus 5.5 KB for `next-intlayer`, and +6-7 KB per page over the native build. It pays for the `next-intl` API surface. If you reach the point where every component has been moved to `useIntlayer`, drop the adapter.
-- **`messages`, `timeZone`, `now` on the provider are ignored.** The formatters are backed by native `Intl` and only the locale influences their output; if you rely on a forced time zone or a fixed `now` for hydration-stable dates, handle it at the call site.
+<AccordionGroup>
+<Accordion header="Routing config moves to intlayer.config.ts">
+
+`createNavigation(routing)` and `createMiddleware(routing)` keep their signature but ignore the argument: locales, default locale and prefix strategy come from Intlayer's `routing` config. If you use `next-intl`'s localised `pathnames` (`/about` to `/a-propos`), the adapter does not interpolate them; Intlayer's `routing.rewrite` covers that case but it is a separate change.
+
+</Accordion>
+<Accordion header="Namespace-less useTranslations() is not bound">
+
+The optimise pass needs a static namespace to know which dictionary to import. A bare call still works, through a runtime registry that references every dictionary, which is exactly the leakage you were trying to remove. Pass the namespace.
+
+</Accordion>
+<Accordion header="The adapter is not free">
+
+8.0 KB of runtime versus 5.5 KB for `next-intlayer`, and +6-7 KB per page over the native build. It pays for the `next-intl` API surface. If you reach the point where every component has been moved to `useIntlayer`, drop the adapter.
+
+</Accordion>
+<Accordion header="messages, timeZone and now on the provider are ignored">
+
+The formatters are backed by native `Intl` and only the locale influences their output. If you rely on a forced time zone or a fixed `now` for hydration-stable dates, handle it at the call site. See [date, time and number formatting](https://intlayer.org/en-GB/blog/date-time-number-formatting-locales).
+
+</Accordion>
+</AccordionGroup>
 
 ## When to use which?
 
-- **Stay on `next-intl`** if your app is small, your bundle is not a concern, and your team is comfortable owning namespaces and `pick()` per page.
-- **Use `@intlayer/next-intl`** if you are on `next-intl` today and want the bundle, leakage and hydration gains, typed keys and the CLI / CMS tooling without a rewrite. This is the recommended entry point for any existing `next-intl` codebase.
-- **Go native (`next-intlayer`)** for new projects, or once the adapter has done its job. It is the lightest of the three (5.5 KB, +0.3 KB per page) and unlocks synchronous server components, per-component `.content.ts` files and the full feature set.
+<AccordionGroup>
+<Accordion header="Stay on next-intl">
+
+Your app is small, your bundle is not a concern, and your team is comfortable owning namespaces and `pick()` per page.
+
+</Accordion>
+<Accordion header="Use @intlayer/next-intl">
+
+You are on `next-intl` today and want the bundle, leakage and hydration gains, typed keys and the CLI / CMS tooling without a rewrite. This is the recommended entry point for any existing `next-intl` codebase.
+
+</Accordion>
+<Accordion header="Go native (next-intlayer)">
+
+For new projects, or once the adapter has done its job. It is the lightest of the three (5.5 KB, +0.3 KB per page) and unlocks synchronous server components, per-component `.content.ts` files and the full feature set. Start with [Intlayer with Next.js](https://intlayer.org/en-GB/doc/environment/nextjs).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Does my application code really stay untouched?">
+
+On Next.js, yes for components: the benchmark build changed `next.config.ts` and `intlayer.config.ts` only. `getRequestConfig` in `src/i18n.ts`, the `messages` prop on the provider and per-page `pick()` calls become dead code you can delete afterwards.
+
+</Question>
+
+<Question title="What happens to ICU messages?">
+
+They keep working. `t("key", { count })`, `t.rich()`, `t.markup()`, `select`, `selectordinal`, `#` and `{ts, date, long}` are resolved by Intlayer's ICU resolver. See [ICU message format](https://intlayer.org/en-GB/blog/icu-message-format).
+
+</Question>
+
+<Question title="Why is the adapter heavier than native next-intlayer?">
+
+It carries the `next-intl` API surface on top of Intlayer's core: `useFormatter`, `t.rich`, the ICU resolver, the navigation helpers. That is 8.0 KB against 5.5 KB, and +6 KB per page. It is the bridge, not the destination.
+
+</Question>
+
+<Question title="Can I migrate component by component?">
+
+Yes. Any component can switch from `useTranslations("about")` to `useIntlayer("about")` with a co-located `.content.ts`. JSON and `.content.ts` dictionaries coexist and merge, so there is no flag day.
+
+</Question>
+
+<Question title="Do localised pathnames work?">
+
+Not through `next-intl`'s `pathnames`: the adapter accepts it for typing but does not interpolate it. Use Intlayer's `routing.rewrite` instead, which emits the localised literals into the type registry.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (the libraries, same benchmark)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (same adapter series)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (same adapter series)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n) (same adapter series)
-- [Migration guide: next-intl to Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [Compatibility adapter reference: next-intl](https://intlayer.org/doc/compatibility/next-intl)
+Same adapter series:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/en-GB/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/en-GB/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/en-GB/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+The libraries compared head to head:
+
+- [next-intl vs Intlayer](https://intlayer.org/en-GB/blog/next-intl-vs-intlayer), same benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/en-GB/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/en-GB/blog/is-next-intl-outdated)
+
+Reference docs:
+
+- [Compat adapter: next-intl](https://intlayer.org/en-GB/doc/compatibility/next-intl)
+- [Migration guide: next-intl to Intlayer](https://intlayer.org/en-GB/doc/migration/next-intl)
+- [Next.js benchmark report](https://intlayer.org/en-GB/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/en-GB/doc/benchmark/tanstack)
+- [Bundle optimization](https://intlayer.org/en-GB/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/en-GB/doc/compiler)
+- [Visual Editor](https://intlayer.org/en-GB/doc/concept/editor), [CMS](https://intlayer.org/en-GB/doc/concept/cms) and [AI translation](https://intlayer.org/en-GB/doc/concept/auto-fill)
 
 ## Conclusion