@intlayer/docs 9.5.5 → 9.5.7

package/blog/en/vue-i18n_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-08-23
+updatedAt: 2026-09-22
 title: vue-i18n vs Intlayer
 description: Compare vue-i18n with Intlayer for internationalization (i18n) in Vue/Nuxt apps
 keywords:
@@ -20,6 +20,8 @@ author: aymericzip
 
 # vue-i18n VS Intlayer | Vue Internationalization (i18n)
 
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 This guide compares two popular i18n options for **Vue 3** (and **Nuxt**): **vue-i18n** and **Intlayer**.
 We focus on modern Vue tooling (Vite, Composition API) and evaluate:
 
@@ -40,6 +42,30 @@ We focus on modern Vue tooling (Vite, Composition API) and evaluate:
 - **vue-i18n** - The de-facto i18n library for Vue. Flexible message formatting (ICU-style), SFC `<i18n>` blocks for local messages, and a big ecosystem. Safety and large-scale maintenance are mostly on you.
 - **Intlayer** - Component-centric content model for Vue/Vite/Nuxt with **strict TS typing**, **build-time checks**, **tree-shaking**, **router & SEO helpers**, optional **Visual Editor/CMS**, and **AI-assisted translations**.
 
+## What it costs at build time
+
+Before the feature tables, the measured part. [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) builds the same Vite + Vue 3 app (10 pages, 10 locales) with each library and records what the browser downloads:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
+| Setup                | Lib size (gz) | Page JS avg (gz) | Page leak | Component avg (gz) |
+| -------------------- | ------------: | ---------------: | --------: | -----------------: |
+| **base** (no i18n)   |        0.0 KB |          41.3 KB |         - |             1.1 KB |
+| `vue-i18n`           |       24.3 KB |         134.9 KB |     90.0% |           196.0 KB |
+| `@intlayer/vue-i18n` |        7.9 KB |          47.0 KB |      0.0% |             8.4 KB |
+| **`vue-intlayer`**   |    **3.9 KB** |      **57.1 KB** |  **0.0%** |         **7.7 KB** |
+
+The `vue-i18n` runtime alone weighs **6x** Intlayer's, every page carries **90% of foreign-page strings**, and a component compiled in isolation drags in **196 KB** because `useI18n()` binds it to the global message tree. The full run, with reactivity and page-load timings, is in the [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark).
+
+<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 in the [Vue benchmark report](https://intlayer.org/doc/benchmark/vue).
+
 ## Side-by-Side Feature Comparison (Vue-focused)
 
 | Feature                                     | **Intlayer**                                                                     | **vue-i18n**                                                                 |
@@ -65,59 +91,74 @@ We focus on modern Vue tooling (Vite, Composition API) and evaluate:
 
 ## Deep-dive comparison
 
-### 1) Architecture & scalability
+<AccordionGroup>
+<Accordion header="1) Architecture & scalability">
 
 - **vue-i18n**: Common setups use **centralized catalogs** per locale (optionally split into files/namespaces). SFC `<i18n>` blocks allow local messages but teams often revert to shared catalogs as projects grow.
 - **Intlayer**: Promotes **per-component dictionaries** stored next to the component they serve. This reduces cross-team conflicts, keeps content discoverable, and naturally limits drift/unused keys.
 
-**Why it matters:** In large Vue apps or design systems, **modular content** scales better than monolithic catalogs.
+**Why it matters:** In large Vue apps or design systems, **modular content** scales better than monolithic catalogs. See [per-component vs centralized i18n](https://intlayer.org/blog/per-component-vs-centralized-i18n).
 
-### 2) TypeScript & safety
+</Accordion>
+<Accordion header="2) TypeScript & safety">
 
 - **vue-i18n**: Good TS support; **strict key typing** typically needs custom schemas/generics and careful conventions.
 - **Intlayer**: **Generates strict types** from your content, giving **IDE autocompletion** and **compile-time errors** for typos/missing keys.
 
 **Why it matters:** Strong typing catches issues **before** runtime.
 
-### 3) Missing translation handling
+</Accordion>
+<Accordion header="3) Missing translation handling">
 
 - **vue-i18n**: **Runtime** warnings/fallbacks (e.g., fall back locale or key).
-- **Intlayer**: **Build-time** detection with warnings/errors across locales and keys.
+- **Intlayer**: **Build-time** detection with warnings/errors across locales and keys, plus `npx intlayer test` in CI.
 
-**Why it matters:** Build-time enforcement keeps production UI clean and consistent.
+**Why it matters:** Build-time enforcement keeps production UI clean and consistent. See [detecting missing translations](https://intlayer.org/blog/detecting-missing-translations).
 
-### 4) Routing & URL strategy (Vue Router/Nuxt)
+</Accordion>
+<Accordion header="4) Routing & URL strategy (Vue Router/Nuxt)">
 
 - **Both** can work with localized routes.
-- **Intlayer** provides helpers to **generate localized paths**, **manage locale prefixes**, and emit **`<link rel="alternate" hreflang>`** for SEO. With Nuxt, it complements the framework’s routing.
+- **Intlayer** provides helpers to **generate localized paths**, **manage locale prefixes**, and emit **`<link rel="alternate" hreflang>`** for SEO. With Nuxt, it complements the framework's routing.
 
-**Why it matters:** Fewer custom glue layers and **cleaner SEO** across locales.
+**Why it matters:** Fewer custom glue layers and **cleaner SEO** across locales. See the [hreflang guide](https://intlayer.org/blog/hreflang-guide-multilingual-seo).
 
-### 5) Performance & loading behavior
+</Accordion>
+<Accordion header="5) Performance & loading behavior">
 
 - **vue-i18n**: Supports async locale messages; avoiding over-bundling is on you (split catalogs carefully).
-- **Intlayer**: **Tree-shakes** at build and **lazy-loads per dictionary/locale**. Unused content doesn’t ship.
+- **Intlayer**: **Tree-shakes** at build and **lazy-loads per dictionary/locale**. Unused content doesn't ship.
 
-**Why it matters:** Smaller bundles and faster startup for multi-locale Vue apps.
+**Why it matters:** Smaller bundles and faster startup for multi-locale Vue apps. The benchmark above puts numbers on it: 134.9 KB against 57.1 KB per page.
 
-### 6) Developer experience & tooling
+</Accordion>
+<Accordion header="6) Developer experience & tooling">
 
-- **vue-i18n**: Mature docs and community; you’ll typically rely on **external localization platforms** for editorial workflows.
-- **Intlayer**: Ships a **free Visual Editor**, optional **CMS** (Git-friendly or externalized), a **VSCode extension**, **CLI/CI** utilities, and **AI-assisted translations** using your own provider keys.
+- **vue-i18n**: Mature docs and community; you'll typically rely on **external localization platforms** for editorial workflows.
+- **Intlayer**: Ships a **free Visual Editor**, optional **CMS** (Git-friendly or externalized), a **VSCode extension**, **CLI/CI** utilities, an **MCP server** and **AI-assisted translations** using your own provider keys.
 
-**Why it matters:** Lower ops cost and a shorter dev–content loop.
+**Why it matters:** Lower ops cost and a shorter dev to content loop.
 
-### 7) SEO, SSR & SSG
+</Accordion>
+<Accordion header="7) SEO, SSR & SSG">
 
 - **Both** work with Vue SSR and Nuxt.
 - **Intlayer**: Adds **SEO helpers** (sitemaps/metadata/`hreflang`) that are framework-agnostic and play nicely with Vue/Nuxt builds.
 
-**Why it matters:** International SEO without bespoke wiring.
+**Why it matters:** International SEO without bespoke wiring. See [internationalization and SEO](https://intlayer.org/blog/SEO-and-i18n).
+
+</Accordion>
+</AccordionGroup>
 
 ## Why Intlayer? (Problem & approach)
 
+![Centralized catalogs versus per-component dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/assets/project_stucture_18n_vs_intlayer.png?raw=true)
+
 Most i18n stacks (including **vue-i18n**) start from **centralized catalogs**:
 
+<Tabs defaultTab="per-locale" group="catalog">
+<Tab label="One file per locale" value="per-locale">
+
 ```bash
 .
 ├── locales
@@ -129,7 +170,8 @@ Most i18n stacks (including **vue-i18n**) start from **centralized catalogs**:
         └── MyComponent.vue
 ```
 
-Or with per-locale folders:
+</Tab>
+<Tab label="One folder per locale" value="per-folder">
 
 ```bash
 .
@@ -148,6 +190,34 @@ Or with per-locale folders:
         └── MyComponent.vue
 ```
 
+</Tab>
+</Tabs>
+
+That folder keeps growing, one namespace per feature, in every locale:
+
+```txt
+locales
+├── EN
+│   ├── blog.json
+│   ├── about.json
+│   ├── auth.json
+│   ├── blog.json
+│   ├── cart.json
+│   ├── categories.json
+│   ├── contact.json
+│   ├── dashboard.json
+│   ├── errors.json
+│   ├── faq.json
+│   ├── footer.json
+│   ├── form.json
+│   ├── home.json
+│   ├── language.json
+│   ├── navbar.json
+│   ├── ... 65 files
+│   └── validation.json
+└── ES
+```
+
 This often slows development as apps grow:
 
 1. **For a new component** you create/edit remote catalogs, wire namespaces, and translate (often via manual copy/paste from AI tools).
@@ -163,7 +233,33 @@ This often slows development as apps grow:
         └── MyComponent.vue
 ```
 
-**Content declaration** (per component):
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="vue-i18n" value="vue-i18n">
+
+```json fileName="./locales/en.json"
+{
+  "componentExample": {
+    "greeting": "Hello World"
+  }
+}
+```
+
+```vue fileName="./components/MyComponent.vue"
+<script setup lang="ts">
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <span>{{ t("componentExample.greeting") }}</span>
+</template>
+```
+
+Every locale file has to be edited by hand, and the key is a plain string: a typo renders as `componentExample.greting` in production.
+
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="./components/MyComponent/myComponent.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -182,8 +278,6 @@ const componentExampleContent = {
 export default componentExampleContent;
 ```
 
-**Usage in Vue** (Composition API):
-
 ```vue fileName="./components/MyComponent/MyComponent.vue"
 <script setup lang="ts">
 import { useIntlayer } from "vue-intlayer"; // Vue integration
@@ -195,6 +289,11 @@ const { greeting } = useIntlayer("component-example");
 </template>
 ```
 
+All locales sit in one typed file next to the component.
+
+</Tab>
+</Tabs>
+
 This approach:
 
 - **Speeds development** (declare once; IDE/AI autocompletes).
@@ -222,20 +321,71 @@ This approach:
 
 ## When to choose which?
 
-- **Choose vue-i18n** if you want the **standard Vue approach**, you’re comfortable managing catalogs/namespaces yourself, and your app is **small to mid-size** (or you already rely on Nuxt i18n).
-- **Choose Intlayer** if you value **component-scoped content**, **strict TypeScript**, **build-time guarantees**, **tree-shaking**, and **batteries-included** routing/SEO/editor tooling-especially for **large, modular Vue/Nuxt codebases**, design-systems, etc.
+<AccordionGroup>
+<Accordion header="Choose vue-i18n">
+
+You want the **standard Vue approach**, you are comfortable managing catalogs and namespaces yourself, and your app is **small to mid-size** (or you already rely on Nuxt i18n). SFC `<i18n>` blocks and runtime `setLocaleMessage()` are features Intlayer deliberately does not replicate.
+
+</Accordion>
+<Accordion header="Choose Intlayer">
+
+You value **component-scoped content**, **strict TypeScript**, **build-time guarantees**, **tree-shaking**, and **batteries-included** routing, SEO and editor tooling, especially for **large, modular Vue/Nuxt codebases** and design systems. 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>
+<Accordion header="Choose @intlayer/vue-i18n">
+
+You are on `vue-i18n` today and want the bundle gains without editing a `.vue` file. The [compat adapter](https://intlayer.org/doc/compatibility/vue-i18n) keeps `createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t` and `v-t`, and serves them from compiled dictionaries. Measured side by side in [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n).
+
+</Accordion>
+</AccordionGroup>
 
 ## Interoperability with vue-i18n
 
 `intlayer` can also help to manage your `vue-i18n` namespaces.
 
-Using `intlayer`, you can declare your content in the format of your favorite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
+Using `intlayer`, you can declare your content in the format of your favorite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`). See the [vue-i18n compatibility doc](https://intlayer.org/doc/compatibility/vue-i18n) and the [Nuxt i18n adapter](https://intlayer.org/doc/compatibility/nuxtjs-i18n).
+
+## FAQ
+
+<FAQ>
+
+<Question title="Is Intlayer a replacement for vue-i18n or a layer on top?">
+
+Both, depending on how you adopt it. `vue-intlayer` is a native runtime with its own `useIntlayer()` composable. `@intlayer/vue-i18n` is a compat adapter that keeps the `vue-i18n` API and swaps what it is bound to, so you can migrate without touching components and move file by file afterwards.
+
+</Question>
+
+<Question title="What happens to my SFC <i18n> blocks?">
+
+The adapter does not read them. Move those messages into your locale JSON, or into a `.content.ts` next to the component, which is the same idea with generated types. That is the one `vue-i18n` feature that does not carry over.
+
+</Question>
+
+<Question title="Does Intlayer work with Nuxt?">
+
+Yes. [Intlayer with Nuxt](https://intlayer.org/doc/environment/nuxt-and-vue) covers multilingual routing, locale detection middleware and sitemap generation. If you are on `@nuxtjs/i18n`, the [Nuxt i18n compat adapter](https://intlayer.org/doc/compatibility/nuxtjs-i18n) is the migration path.
+
+</Question>
+
+<Question title="Can I keep my locales/{locale}.json as the source of truth?">
+
+Yes. The [JSON sync plugin](https://intlayer.org/doc/compatibility/vue-i18n) reads them with the `vue-i18n` dialect (`{name}`, `{0}`, `"car | cars"` pipe plurals) and writes translations back when the CLI or the CMS updates them.
+
+</Question>
+
+<Question title="Does ICU work with Intlayer on Vue?">
+
+Native ICU support is a work in progress. The `@intlayer/vue-i18n` adapter resolves `vue-i18n`'s own message syntax, including pipe plurals and named and list interpolation. For Intlayer's pluralization model, see [enumeration content](https://intlayer.org/doc/concept/content/enumeration).
+
+</Question>
+
+</FAQ>
 
 ## GitHub STARs
 
 GitHub stars are a strong indicator of a project's popularity, community trust, and long-term relevance. While not a direct measure of technical quality, they reflect how many developers find the project useful, follow its progress, and are likely to adopt it. For estimating the value of a project, stars help compare traction across alternatives and provide insights into ecosystem growth.
 
-[![Star History Chart](https://api.star-history.com/svg?repos=intlify/vue-i18n&repos=aymericzip/intlayer&type=Date)](https://star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+[![Star History Chart](https://api.star-history.com/chart?repos=intlify%2Fvue-i18n%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
 
 ## Conclusion
 
@@ -244,4 +394,15 @@ Both **vue-i18n** and **Intlayer** localize Vue apps well. The difference is **h
 - With **Intlayer**, **modular content**, **strict TS**, **build-time safety**, **tree-shaken bundles**, and **router/SEO/editor tooling** come **out of the box**.
 - If your team prioritizes **maintainability and speed** in a multi-locale, component-driven Vue/Nuxt app, Intlayer offers the **most complete** experience today.
 
+## Further reading
+
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark), the measured run behind the table above
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n), the adapter on the same app
+- [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)
+- [Using Intlayer with vue-i18n](https://intlayer.org/blog/intlayer-with-vue-i18n)
+- [Vue benchmark report](https://intlayer.org/doc/benchmark/vue)
+- [Migration guide: vue-i18n to Intlayer](https://intlayer.org/doc/migration/vue-i18n)
+- [Bundle optimization](https://intlayer.org/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/doc/compiler)
+
 Refer to ['Why Intlayer?' doc](https://intlayer.org/doc/why) for more details.

package/blog/en-GB/i18next_vs_intlayer-i18next.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "i18next vs @intlayer/i18next: Same API, Different Bundle"
 description: What changes when a React or Next.js app keeps its i18next, react-i18next and next-i18next calls but serves them through the @intlayer/i18next adapters. Per-page JavaScript, component size, leakage and hydration measured on the same code, plus what the adapters keep, ignore and cannot replace.
 keywords:
@@ -28,6 +28,8 @@ author: aymericzip
 
 # i18next VS @intlayer/i18next | Same API, Different Bundle
 
+![i18next VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/i18next`, `@intlayer/react-i18next` and `@intlayer/next-i18next` are compat adapters. They expose the `i18next` API your code already uses (`useTranslation`, `t()`, `<Trans>`, `i18n.changeLanguage()`, `getFixedT`, `serverSideTranslations`...) and serve it from dictionaries compiled by Intlayer. The components do not change. The runtime underneath them does.
 
 This article measures that swap on the same Next.js application, built once with `next-i18next` and once with `@intlayer/next-i18next`. The numbers come from [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). For `i18next` and Intlayer compared as libraries, read [i18next vs Intlayer](https://intlayer.org/en-GB/blog/i18next-vs-intlayer). This one is about what the adapter changes when you keep your code as it is.
@@ -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,10 +135,21 @@ For each build, the suite records:
 - **Hydration and switching are faster.** Hydration goes from 15.6 ms to **11.3 ms** (and from 27.7 ms in the `dynamic` setup, where the backend fetch sits on the critical path). Locale switching goes from 15-16 ms to **11-12 ms**.
 - **The adapter is not the native runtime.** `next-intlayer` lands at **141.3 KB**, +0.3 KB over the base app. The adapter carries the `i18next` API surface (interpolation dialect, plural and context suffix resolution, `<Trans>` tag parsing) on top of Intlayer's core: 9.4 KB and +9.4 KB per page over native. 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).
+
 > The `react-i18next` adapter on Vite / TanStack Start was not part of this run. The `react-i18next` baseline on TanStack Start is in [i18next vs Intlayer](https://intlayer.org/en-GB/blog/i18next-vs-intlayer): 127-184 KB per page and a 123-185 ms locale switch when the backend is lazy.
 
 ## 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 `components/` changed, so the gains come from what `useTranslation` is bound to.
 
 **With `i18next`**, the binding is the global instance. Whatever was loaded into it (all locales in `static`, the active locale's whole namespace in `dynamic`) is reachable from every component that calls `useTranslation()`. The bundler cannot split below what the instance holds, and the runtime cannot know which keys a component will ask for.
@@ -149,6 +166,10 @@ Nothing in `components/` changed, so the gains come from what `useTranslation` i
     └── About.tsx                     # useTranslation(); t("about.title")
 ```
 
+Whatever the instance holds ships to every page, 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)
+
 **With `@intlayer/next-i18next`**, the binding is the dictionary. `syncJSON` turns each namespace file into a dictionary; the optimize pass hands the component the dictionary it names, as an import the bundler can trace and split per page and per locale.
 
 ```bash
@@ -297,26 +318,112 @@ export default defineConfig({
 
 ## Limits to know before you start
 
-- **Backends and detectors are inert.** `i18n.use(HttpBackend)` calls the plugin's `init` and nothing else. If your app relied on fetching translations from a CMS at runtime, that flow is gone; use Intlayer's CMS or the `intlayer pull` / `push` commands instead.
-- **`resources` is ignored, not merged.** Unlike some other adapters, `@intlayer/i18next` does not use inline `resources` as a fallback. Every key must exist in the synced dictionaries, which `intlayer test` verifies.
-- **App Router needs the provider edit.** One file, shown above. Pages Router with `appWithTranslation` needs nothing.
-- **`next-i18next.config.js` is not read.** `localePath`, `fallbackLng`, `reloadOnPrerender` and friends have no equivalent; locales and fallback come from `intlayer.config.ts`.
-- **The adapter is not free.** 9.4 KB of runtime and +9.4 KB per page over `next-intlayer`. Once every component has moved to `useIntlayer`, drop it.
+<AccordionGroup>
+<Accordion header="Backends and detectors are inert">
+
+`i18n.use(HttpBackend)` calls the plugin's `init` and nothing else. If your app relied on fetching translations from a CMS at runtime, that flow is gone; use the [Intlayer CMS](https://intlayer.org/en-GB/doc/concept/cms) or the `intlayer pull` / `push` commands instead. Locale detection becomes Intlayer's routing config (URL prefix, cookie, header).
+
+</Accordion>
+<Accordion header="resources is ignored, not merged">
+
+Unlike some other adapters, `@intlayer/i18next` does not use inline `resources` as a fallback. Every key must exist in the synced dictionaries, which `intlayer test` verifies.
+
+</Accordion>
+<Accordion header="App Router needs the provider edit">
+
+One file, shown above. Pages Router with `appWithTranslation` needs nothing.
+
+</Accordion>
+<Accordion header="next-i18next.config.js is not read">
+
+`localePath`, `fallbackLng`, `reloadOnPrerender` and friends have no equivalent; locales and fallback come from `intlayer.config.ts`.
+
+</Accordion>
+<Accordion header="The adapter is not free">
+
+9.4 KB of runtime and +9.4 KB per page over `next-intlayer`. Once every component has moved to `useIntlayer`, drop it.
+
+</Accordion>
+</AccordionGroup>
 
 ## When to use which?
 
-- **Stay on `i18next`** if your app depends on runtime backends (translations served by a CMS at request time), on the plugin ecosystem, or on a non-React target the adapters do not cover.
-- **Use `@intlayer/*`** if you are on `react-i18next` / `next-i18next` and want the 68 KB, the 8x smaller components, 0% leakage, typed keys and CI checks without a rewrite. This is the entry point for an existing `i18next` codebase.
-- **Go native (`next-intlayer` / `react-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 and per-component `.content.ts` files.
+<AccordionGroup>
+<Accordion header="Stay on i18next">
+
+Your app depends on runtime backends (translations served by a CMS at request time), on the plugin ecosystem, or on a non-React target the adapters do not cover.
+
+</Accordion>
+<Accordion header="Use @intlayer/*">
+
+You are on `react-i18next` / `next-i18next` and want the 68 KB, the 8x smaller components, 0% leakage, typed keys and CI checks without a rewrite. This is the entry point for an existing `i18next` codebase.
+
+</Accordion>
+<Accordion header="Go native (next-intlayer / react-intlayer)">
+
+For new projects, or once the adapter has done its job. It has the lightest runtime (5.5 KB, +0.3 KB per page) and unlocks synchronous server components and per-component `.content.ts` files. Start with [Intlayer with Next.js](https://intlayer.org/en-GB/doc/environment/nextjs) or [with Vite and React](https://intlayer.org/en-GB/doc/environment/vite-and-react).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Where do the 68 KB come from?">
+
+From `resources: { en, fr, ... }`. The naive `next-i18next` setup imports every locale's JSON into `init()`, so every page carries every namespace in every language: **218.5 KB** per page. The adapter never bundles that block; it hands each component the dictionary it names, in the active locale.
+
+</Question>
+
+<Question title="Do my <Trans> components keep working?">
+
+Yes, with `components`, numbered `<1>...</1>` tags and `values`. So do `{{interpolation}}`, `$t(key)` nesting, `key_one` / `key_other` plurals (evaluated with `Intl.PluralRules`), context suffixes and `returnObjects`.
+
+</Question>
+
+<Question title="What if I use a single translation.json per locale?">
+
+Set `splitKeys: false` in the `syncJSON` plugin. The whole file stays one dictionary and a bare `useTranslation()` keeps resolving against it.
+
+</Question>
+
+<Question title="Is this the same as migrating to Intlayer?">
+
+No, it is the bridge. The adapter keeps the `i18next` API and costs 9.4 KB of runtime; native `next-intlayer` costs 5.5 KB and adds synchronous server components and co-located `.content.ts` files. You can move component by component, since JSON and `.content.ts` dictionaries coexist.
+
+</Question>
+
+<Question title="Can translators keep working the way they do today?">
+
+Yes. `locales/{lng}/{ns}.json` stays the source of truth: `syncJSON` reads it with the i18next dialect and writes translations back when the CLI or the CMS updates them.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [i18next vs Intlayer](https://intlayer.org/en-GB/blog/i18next-vs-intlayer) (the libraries, same benchmark)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/en-GB/blog/next-intl-vs-intlayer-next-intl) (same adapter series)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/en-GB/blog/lingui-vs-intlayer-lingui) (same adapter series)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/en-GB/blog/vue-i18n-vs-intlayer-vue-i18n) (same adapter series)
+Same adapter series:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/en-GB/blog/next-intl-vs-intlayer-next-intl)
+- [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:
+
+- [i18next vs Intlayer](https://intlayer.org/en-GB/blog/i18next-vs-intlayer), same 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)
+- [Is i18next outdated?](https://intlayer.org/en-GB/blog/is-i18next-outdated)
+
+Reference docs:
+
+- Compat adapters: [i18next](https://intlayer.org/en-GB/doc/compatibility/i18next), [react-i18next](https://intlayer.org/en-GB/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/en-GB/doc/compatibility/next-i18next)
 - Migration guides: [i18next](https://intlayer.org/en-GB/doc/migration/i18next), [react-i18next](https://intlayer.org/en-GB/doc/migration/react-i18next), [next-i18next](https://intlayer.org/en-GB/doc/migration/next-i18next)
-- Compat adapter references: [i18next](https://intlayer.org/en-GB/doc/compatibility/i18next), [react-i18next](https://intlayer.org/en-GB/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/en-GB/doc/compatibility/next-i18next)
+- [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