@intlayer/docs 9.5.6 → 9.5.7

package/blog/en/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 deserialize 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/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 optimized `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/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 localized `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 optimize 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 localized `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 optimize 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/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/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/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 localized 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 localized 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)
+Same adapter series:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+The libraries compared head to head:
+
+- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer), same benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/blog/is-next-intl-outdated)
+
+Reference docs:
+
+- [Compat adapter: next-intl](https://intlayer.org/doc/compatibility/next-intl)
 - [Migration guide: next-intl to Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [Compat adapter reference: next-intl](https://intlayer.org/doc/compatibility/next-intl)
+- [Next.js benchmark report](https://intlayer.org/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/doc/benchmark/tanstack)
+- [Bundle optimization](https://intlayer.org/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/doc/compiler)
+- [Visual Editor](https://intlayer.org/doc/concept/editor), [CMS](https://intlayer.org/doc/concept/cms) and [AI translation](https://intlayer.org/doc/concept/auto-fill)
 
 ## Conclusion
 

package/blog/en/next-intl_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs Intlayer: 2026 Benchmark & Comparison"
 description: Bundle size, content leakage, locale-switch reactivity and developer experience measured on Next.js and TanStack Start. Which i18n library should you pick in 2026?
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # next-intl VS Intlayer | Next.js Internationalization (i18n) Benchmark
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `next-intl` is the most popular i18n library for Next.js. Intlayer is a compiler-based, component-scoped alternative. Both localize an App Router application. The question is what each one costs once the app is built.
 
 This article is not a tutorial. It's a comparison backed by numbers from [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), an open-source benchmark suite that builds the same application with each library and measures what the browser actually downloads and executes.
@@ -96,6 +98,10 @@ For each build, the suite records:
 
 ### Results on Next.js (App Router)
 
+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 |
@@ -116,6 +122,15 @@ For each build, the suite records:
 - **Component size.** A component that calls `useTranslations()` compiles to 21.8 KB on average; the same component with `useIntlayer()` compiles to 6.9 KB. In the `scoped-static` setup the `next-intl` components jump to 80.1 KB because each one inlines its namespace catalog.
 - **Reactivity and hydration** are in the same ballpark for both libraries on Next.js (15-18 ms). Neither one is a bottleneck here.
 
+<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 (`use-intl`)
 
 `use-intl` is the framework-agnostic core of `next-intl`. Same API, same message format. Comparing it against `intlayer` on TanStack Start removes the Next.js-specific parts of the equation.
@@ -139,8 +154,19 @@ For each build, the suite records:
 - **Component size is where the architecture shows**: 76-87 KB per component with `use-intl` versus 6-8 KB with Intlayer. `useTranslations()` binds each component to the global message tree; `useIntlayer()` binds it to its own dictionary.
 - **Locale switch** is 2x-4x faster with Intlayer (3 ms vs 7-21 ms).
 
+<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? Centralized catalogs 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)
+
 `next-intl` follows the classic model: one JSON per locale, loaded in `getRequestConfig`, pushed into a `NextIntlClientProvider`, read through `t("namespace.key")`.
 
 ```bash
@@ -162,6 +188,10 @@ For each build, the suite records:
 
 The runtime cannot know which keys a page will use, so the safe default is to send the whole catalog. Optimizing means **you** split the catalog into namespaces, **you** decide which namespaces each page needs, and **you** keep that mapping in sync as components move around. The benchmark's `scoped-dynamic` row is the reward for that work, and most teams never get there.
 
+The cost of not getting there 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)
+
 Intlayer flips the responsibility. Content is declared next to the component:
 
 ```bash
@@ -189,7 +219,8 @@ At build time the compiler (`@intlayer/swc` / `@intlayer/babel`) sees which comp
 
 ### Client component
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```json fileName="messages/en.json"
 {
@@ -224,7 +255,8 @@ export const Counter = () => {
 
 > Remember to include the `counter` namespace in the messages passed to `NextIntlClientProvider` on every page that renders this component.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -265,11 +297,15 @@ export const Counter = () => {
 
 Nothing to register on the page: the component brings its own content.
 
+</Tab>
+</Tabs>
+
 ### Synchronous server component
 
 Design-system pieces (navbar, footer, cards) are often server components rendered as children of client components, so they cannot be `async`.
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -287,7 +323,8 @@ export const ServerCounter = ({ t, formattedCount }: ServerCounterProps) => (
 
 The page has to `await getTranslations("counter")` and `await getFormatter()`, then thread the results down as props. The component is no longer self-contained.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -306,9 +343,13 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ### Metadata
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import type { Metadata } from "next";
@@ -341,7 +382,8 @@ export const generateMetadata = async ({
 };
 ```
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import { getIntlayer, getMultilingualUrls } from "intlayer";
@@ -365,6 +407,9 @@ export const generateMetadata = async ({
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## Keep the next-intl API, get Intlayer's output
 
 You don't have to rewrite components to get the benchmark numbers above. `@intlayer/next-intl` is a drop-in adapter: it keeps `useTranslations`, `getTranslations`, `useFormatter`, `t.rich()`, ICU plurals and the `next-intl/navigation` helpers, and serves them from Intlayer dictionaries compiled by the Intlayer compiler.
@@ -386,17 +431,84 @@ See the [next-intl migration guide](https://intlayer.org/doc/migration/next-intl
 
 ## When to choose which?
 
-- **Choose next-intl** if you want the ecosystem standard for Next.js, you rely on ICU MessageFormat, your app is small to mid-size, or you integrate with a translation platform (Crowdin, Phrase, Lokalise...) that expects centralized JSON. Budget the time to namespace catalogs and pick messages per page 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**, 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 `@intlayer/next-intl`** if you are already on `next-intl` and want the bundle gains without a rewrite.
+<AccordionGroup>
+<Accordion header="Choose next-intl">
+
+You want the ecosystem standard for Next.js, you rely on ICU MessageFormat, your app is small to mid-size, or you integrate with a translation platform (Crowdin, Phrase, Lokalise...) that expects centralized JSON. Budget the time to namespace catalogs and `pick()` messages per page 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**, 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 @intlayer/next-intl">
+
+You are already on `next-intl` and want the bundle gains without a rewrite. The [compat adapter](https://intlayer.org/doc/compatibility/next-intl) keeps your imports and your `messages/{locale}.json` as the source of truth. Measured side by side in [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Is next-intl slower than Intlayer?">
+
+Not at render time. The difference is what ships: `next-intl` costs **+12.6 KB gzip** of runtime on every page and, in the setups most teams run, sends ~90% of foreign-page strings with each page. Locale switching and hydration are comparable on Next.js (15-18 ms); on TanStack Start, `use-intl` takes 7-21 ms against 3-4 ms for Intlayer.
+
+</Question>
+
+<Question title="Can I reach 0% leakage with next-intl?">
+
+Yes, with the `scoped-dynamic` setup: split `messages/{locale}.json` into one namespace per route, then `pick(messages, [...])` in every page and keep that mapping correct as components move. The benchmark's `scoped-*` rows are exactly that work. Intlayer reaches 0% without it because the compiler scopes content per component. See [bundle optimization](https://intlayer.org/doc/concept/bundle-optimization).
+
+</Question>
+
+<Question title="Do I have to rewrite my components to migrate?">
+
+No. `@intlayer/next-intl` keeps `useTranslations`, `getTranslations`, `useFormatter`, `t.rich()`, ICU plurals and the navigation helpers, and serves them from compiled dictionaries. One plugin line in `next.config.ts`. Step by step in the [next-intl migration guide](https://intlayer.org/doc/migration/next-intl).
+
+</Question>
+
+<Question title="Does Intlayer support ICU MessageFormat?">
+
+ICU support is a work in progress on the native API. The compat adapters (`@intlayer/next-intl`, `@intlayer/use-intl`) do run ICU: plurals, `select`, `selectordinal`, `#` and `{ts, date, long}` go through Intlayer's ICU resolver. Read [ICU message format](https://intlayer.org/blog/icu-message-format) for the details.
+
+</Question>
+
+<Question title="Can I keep my messages/{locale}.json files?">
+
+Yes. The [JSON sync plugin](https://intlayer.org/doc/compatibility/next-intl) reads them, splits their top-level keys into dictionaries, and writes translations back to the same files when the CLI or the CMS updates them. Your translators' workflow does not change.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [i18next vs Intlayer](https://intlayer.org/blog/i18next-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:
+
+- [i18next vs Intlayer](https://intlayer.org/blog/i18next-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 next-intl:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl), the adapter measured on the same app
 - [Is next-intl outdated?](https://intlayer.org/blog/is-next-intl-outdated)
+- [Using Intlayer with next-intl](https://intlayer.org/blog/intlayer-with-next-intl)
+- [How to internationalize a Next.js app with next-intl](https://intlayer.org/blog/nextjs-internationalization-using-next-intl)
+
+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: next-intl](https://intlayer.org/doc/compatibility/next-intl) and [migration guide](https://intlayer.org/doc/migration/next-intl)
+- [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/vue-i18n_vs_intlayer-vue-i18n.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "vue-i18n vs @intlayer/vue-i18n: Same API, Different Bundle"
 description: What changes when a Vue 3 app keeps its vue-i18n calls but serves them through the @intlayer/vue-i18n compat adapter. Per-page JavaScript, runtime size, component size and leakage measured on the same Vite + Vue code, plus what the adapter keeps, ignores and cannot replace.
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # vue-i18n VS @intlayer/vue-i18n | Same API, Different Bundle
 
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 `@intlayer/vue-i18n` is a compat adapter: it exposes the `vue-i18n` API (`createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t`, `v-t`, `i18n.global.locale`...) and serves it from dictionaries compiled by Intlayer. Your `.vue` files do not change. What `t("footer.github")` is bound to does.
 
 This article measures that swap on the same Vite + Vue 3 application, built once with `vue-i18n` and once with the adapter. The numbers come from [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). For `vue-i18n` and Intlayer compared as libraries, read [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) and the [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark). This one is about what the adapter changes when you keep your components as they are.
@@ -105,6 +107,10 @@ For each build, the suite records:
 
 ### Results on Vite + Vue 3
 
+Pick the metrics and the libraries you care about:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
 | Setup                    | Strategy | Lib size (gz) | Lib size (min) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |  Page load |
 | ------------------------ | -------- | ------------: | -------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ---------: |
 | **base** (no i18n)       | -        |        0.0 KB |         0.0 KB |          41.3 KB |        0.0% |         - |             1.1 KB |         1.8 ms |    10.8 ms |
@@ -124,11 +130,24 @@ For each build, the suite records:
 - **Reactivity and page load.** Locale switching is cheap for both (1.5-2.8 ms); Vue's reactivity system makes it so once messages are in memory. Page load goes from 13.6 ms to **9.3 ms**, in line with 88 KB less JavaScript to parse.
 - **About the native rows.** `vue-intlayer` in this run bundled every locale in `static` mode and landed at 57.1 KB with a 3.9 KB runtime; the adapter's synced dictionaries carried fewer foreign-locale strings, hence the lower per-page figure. The native runtime remains the lightest of the three, and its `.content.ts` model is where SFC `<i18n>` blocks find their equivalent.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_vue.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Full table, every library and every strategy, in the [Vue benchmark report](https://intlayer.org/doc/benchmark/vue).
+
 ## 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 `src/components/` changed, so the gains come from what `useI18n` is bound to.
 
-**With `vue-i18n`**, the binding is the global instance. `createI18n({ messages: { en, fr, ... } })` is one import that holds everything; every component that calls `useI18n()` can reach all of it, so the bundler cannot split below the instance. Optimizing means _you_ split `en.json` by route, call `setLocaleMessage()` in a router guard, and keep the route-to-file map correct as components move.
+**With `vue-i18n`**, the binding is the global instance. `createI18n({ messages: { en, fr, ... } })` is one import that holds everything; every component that calls `useI18n()` can reach all of it, so the bundler cannot split below the instance. Optimizing means _you_ split `en.json` by route, call `setLocaleMessage()` in a router guard, and keep the route-to-file map correct as components move. The waste 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)
 
 ```bash
 .
@@ -258,26 +277,107 @@ export const i18n = createI18n({ locale: "en" });
 
 ## Limits to know before you start
 
-- **SFC `<i18n>` blocks are not read.** If your messages live inside components, they need to move to the locale files (or to `.content.ts`, which is the same idea with types).
-- **Runtime message loading is gone.** `setLocaleMessage()` and `mergeLocaleMessage()` warn and return. Translations fetched from a CMS at runtime need Intlayer's CMS, or the `intlayer pull` / `push` commands.
-- **`messages` is a fallback, not free.** Keeping the JSON imports in `createI18n()` keeps the 75 KB in the bundle. Delete them once `intlayer test` passes.
-- **The adapter is not the native runtime.** 7.9 KB against 3.9 KB for `vue-intlayer`. Once every component has moved to `useIntlayer`, drop it.
+<AccordionGroup>
+<Accordion header="SFC <i18n> blocks are not read">
+
+If your messages live inside components, they need to move to the locale files, or to `.content.ts`, which is the same idea with generated types.
+
+</Accordion>
+<Accordion header="Runtime message loading is gone">
+
+`setLocaleMessage()` and `mergeLocaleMessage()` warn and return. Translations fetched from a CMS at runtime need the [Intlayer CMS](https://intlayer.org/doc/concept/cms), or the `intlayer pull` / `push` commands.
+
+</Accordion>
+<Accordion header="messages is a fallback, not free">
+
+Keeping the JSON imports in `createI18n()` keeps the 75 KB in the bundle. Delete them once `intlayer test` passes.
+
+</Accordion>
+<Accordion header="The adapter is not the native runtime">
+
+7.9 KB against 3.9 KB for `vue-intlayer`. Once every component has moved to `useIntlayer`, drop it.
+
+</Accordion>
+</AccordionGroup>
 
 ## When to use which?
 
-- **Stay on `vue-i18n`** if your app depends on SFC `<i18n>` blocks, on runtime `setLocaleMessage()` flows, or if 90 KB per page is not a concern for your audience.
-- **Use `@intlayer/vue-i18n`** if you are on `vue-i18n` and want the 88 KB, the 23x smaller components, 0% page leakage, typed keys and CI checks without editing a `.vue` file. This is the entry point for an existing `vue-i18n` codebase.
-- **Go native (`vue-intlayer`)** for new projects, or once the adapter has done its job. It has the lightest runtime (3.9 KB) and the per-component `.content.ts` model that replaces `<i18n>` blocks with typed content.
+<AccordionGroup>
+<Accordion header="Stay on vue-i18n">
+
+Your app depends on SFC `<i18n>` blocks, on runtime `setLocaleMessage()` flows, or 90 KB per page is not a concern for your audience.
+
+</Accordion>
+<Accordion header="Use @intlayer/vue-i18n">
+
+You are on `vue-i18n` and want the 88 KB, the 23x smaller components, 0% page leakage, typed keys and CI checks without editing a `.vue` file. This is the entry point for an existing `vue-i18n` codebase.
+
+</Accordion>
+<Accordion header="Go native (vue-intlayer)">
+
+For new projects, or once the adapter has done its job. It has the lightest runtime (3.9 KB) and the per-component `.content.ts` model that replaces `<i18n>` blocks with typed content. Start with [Intlayer with Vue](https://intlayer.org/doc/environment/vite-and-vue) or [with Nuxt](https://intlayer.org/doc/environment/nuxt-and-vue).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Do I have to edit my .vue files?">
+
+No. The benchmark build changed `vite.config.ts`, `intlayer.config.ts` and one line in `src/i18n.ts`, the `messages` import. Every `useI18n()`, `$t`, `v-t` and Options API call site stayed as it was.
+
+</Question>
+
+<Question title="Why is the component size 23x smaller?">
+
+Because `useI18n()` stops reaching the global instance. `createI18n({ messages })` holds every message of every locale, so a component compiled in isolation drags in 196 KB. With the adapter it reaches its own dictionary: 8.4 KB.
+
+</Question>
+
+<Question title="What about d() and n() formatting?">
+
+Kept. `datetimeFormats` and `numberFormats` passed to `createI18n()` are honored, backed by native `Intl`. See [date, time and number formatting](https://intlayer.org/blog/date-time-number-formatting-locales).
+
+</Question>
+
+<Question title="Does it work with Nuxt?">
+
+`@intlayer/vue-i18n` targets Vite + Vue. For `@nuxtjs/i18n`, use the [Nuxt i18n compat adapter](https://intlayer.org/doc/compatibility/nuxtjs-i18n), and see [Intlayer with Nuxt](https://intlayer.org/doc/environment/nuxt-and-vue) for the native setup.
+
+</Question>
+
+<Question title="Can I migrate component by component?">
+
+Yes. Any component can switch from `useI18n()` to `useIntlayer("footer")` with a co-located content file. JSON and `.content.ts` dictionaries coexist and merge.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) (features and DX)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (the libraries, same benchmark)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl) (same adapter series)
-- [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)
+Same adapter series:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl)
+- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui)
+
+The libraries compared head to head:
+
+- [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer), features and DX
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark), the same run in full
+- [Is vue-i18n outdated?](https://intlayer.org/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/blog/how-to-pick-vue-i18n-library)
+
+Reference docs:
+
+- [Compat adapter: vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n) and [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
 - [Migration guide: vue-i18n to Intlayer](https://intlayer.org/doc/migration/vue-i18n)
-- [Compat adapter reference: vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n), [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
+- [Vue benchmark report](https://intlayer.org/doc/benchmark/vue)
+- [Bundle optimization](https://intlayer.org/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/doc/compiler)
+- [Visual Editor](https://intlayer.org/doc/concept/editor), [CMS](https://intlayer.org/doc/concept/cms) and [AI translation](https://intlayer.org/doc/concept/auto-fill)
 
 ## Conclusion