@intlayer/docs 9.5.5 → 9.5.7

package/blog/en-GB/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 internationalisation (i18n) in Vue/Nuxt apps
 keywords:
@@ -20,6 +20,8 @@ author: aymericzip
 
 # vue-i18n VS Intlayer | Vue Internationalisation (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 large ecosystem. Safety and large-scale maintenance are mostly your responsibility.
 - **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/en-GB/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/en-GB/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 **centralised catalogues** per locale (optionally split into files/namespaces). SFC `<i18n>` blocks allow local messages but teams often revert to shared catalogues as projects grow.
+- **vue-i18n**: Common setups use **centralised catalogues** per locale (optionally split into files/namespaces). SFC `<i18n>` blocks allow local messages but teams often revert to shared catalogues as projects grow. See [per-component vs centralized i18n](https://intlayer.org/en-GB/blog/per-component-vs-centralized-i18n).
 - **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 catalogues.
 
-### 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, providing **IDE autocompletion** and **compile-time errors** for typos or 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., fallback locale or key).
-- **Intlayer**: **Build-time** detection with warnings/errors across locales and keys.
+- **vue-i18n**: **Runtime** warnings/fallbacks (e.g., fallback locale or key). See [detecting missing translations](https://intlayer.org/en-GB/blog/detecting-missing-translations).
+- **Intlayer**: **Build-time** detection with warnings/errors across locales and keys., plus `npx intlayer test` in CI.
 
 **Why it matters:** Build-time enforcement keeps the production UI clean and consistent.
 
-### 4) Routing & URL strategy (Vue Router/Nuxt)
+</Accordion>
+<Accordion header="4) Routing & URL strategy (Vue Router/Nuxt)">
 
-- **Both** can work with localised routes.
+- **Both** can work with localised routes. See the [hreflang guide](https://intlayer.org/en-GB/blog/hreflang-guide-multilingual-seo).
 - **Intlayer** provides helpers to **generate localised 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.
 
-### 5) Performance & loading behaviour
+</Accordion>
+<Accordion header="5) Performance & loading behavior">
 
-- **vue-i18n**: Supports async locale messages; avoiding over-bundling is your responsibility (split catalogues carefully).
+- **vue-i18n**: Supports async locale messages; avoiding over-bundling is your responsibility (split catalogues carefully). The benchmark above puts numbers on it: 134.9 KB against 57.1 KB per page.
 - **Intlayer**: **Tree-shakes** at build and **lazy-loads per dictionary/locale**. Unused content isn’t shipped.
 
 **Why it matters:** Smaller bundles and faster startup for multi-locale Vue apps.
 
-### 6) Developer experience & tooling
+</Accordion>
+<Accordion header="6) Developer experience & tooling">
 
 - **vue-i18n**: Mature docs and community; you’ll typically rely on **external localisation platforms** for editorial workflows.
-- **Intlayer**: Ships a **free Visual Editor**, optional **CMS** (Git-friendly or externalised), a **VSCode extension**, **CLI/CI** utilities, and **AI-assisted translations** using your own provider keys.
+- **Intlayer**: Ships a **free Visual Editor**, optional **CMS** (Git-friendly or externalised), a **VSCode extension**, **CLI/CI** utilities, and **AI-assisted translations** using your own provider keys., an **MCP server**
 
 **Why it matters:** Lower ops cost and a shorter dev–content loop.
 
-### 7) SEO, SSR & SSG
+</Accordion>
+<Accordion header="7) SEO, SSR & SSG">
 
-- **Both** work with Vue SSR and Nuxt.
+- **Both** work with Vue SSR and Nuxt. See [internationalization and SEO](https://intlayer.org/en-GB/blog/SEO-and-i18n).
 - **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.
 
+</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 **centralised catalogues**:
 
+<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 **centralised catalogues**:
         └── 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 catalogues, 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";
@@ -173,8 +269,8 @@ const componentExampleContent = {
   content: {
     greeting: t({
       en: "Hello World",
-      es: "Hola Mundo",
       fr: "Bonjour le monde",
+      es: "Hola Mundo",
     }),
   },
 } satisfies Dictionary;
@@ -182,11 +278,10 @@ 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
+
 const { greeting } = useIntlayer("component-example");
 </script>
 
@@ -195,6 +290,11 @@ const { greeting } = useIntlayer("component-example");
 </template>
 ```
 
+All locales sit in one typed file next to the component.
+
+</Tab>
+</Tabs>
+
 This approach:
 
 - **Speeds up development** (declare once; IDE/AI autocompletes).
@@ -222,20 +322,71 @@ This approach:
 
 ## When to choose which?
 
-- **Choose vue-i18n** if you want the **standard Vue approach**, you’re comfortable managing catalogues/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/en-GB/doc/environment/vite-and-vue) or [with Nuxt](https://intlayer.org/en-GB/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/en-GB/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/en-GB/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 favourite 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 favourite 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/en-GB/doc/compatibility/vue-i18n) and the [Nuxt i18n adapter](https://intlayer.org/en-GB/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/en-GB/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/en-GB/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/en-GB/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/en-GB/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 +395,15 @@ Both **vue-i18n** and **Intlayer** localise 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 prioritises **maintainability and speed** in a multi-locale, component-driven Vue/Nuxt app, Intlayer offers the **most complete** experience today.
 
-Refer to ['Why Intlayer?' doc](https://intlayer.org/doc/why) for more details.
+## Further reading
+
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/en-GB/blog/vue-i18n-vs-intlayer-benchmark), the measured run behind the table above
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/en-GB/blog/vue-i18n-vs-intlayer-vue-i18n), the adapter on the same app
+- [Is vue-i18n outdated?](https://intlayer.org/en-GB/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/en-GB/blog/how-to-pick-vue-i18n-library)
+- [Using Intlayer with vue-i18n](https://intlayer.org/en-GB/blog/intlayer-with-vue-i18n)
+- [Vue benchmark report](https://intlayer.org/en-GB/doc/benchmark/vue)
+- [Migration guide: vue-i18n to Intlayer](https://intlayer.org/en-GB/doc/migration/vue-i18n)
+- [Bundle optimization](https://intlayer.org/en-GB/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/en-GB/doc/compiler)
+
+Refer to ['Why Intlayer?' doc](https://intlayer.org/en-GB/doc/why) for more details.

package/blog/en-GB/vue-i18n_vs_intlayer_benchmark.md

@@ -241,5 +241,121 @@ const count = ref(0);
 **Intlayer**
 
 ```ts fileName="src/components/Counter/Counter.content.ts"
+import { t, type Dictionary } from "intlayer";
 
+const counterContent = {
+  key: "counter",
+  content: {
+    label: t({ en: "Counter", fr: "Compteur" }),
+    increment: t({ en: "Increment", fr: "Incrémenter" }),
+  },
+} satisfies Dictionary;
+
+export default counterContent;
+```
+
+```vue fileName="src/components/Counter/Counter.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { useIntlayer } from "vue-intlayer";
+import { useNumber } from "vue-intlayer/format";
+
+const { label, increment } = useIntlayer("counter");
+const number = useNumber();
+const count = ref(0);
+</script>
+
+<template>
+  <div>
+    <p>{{ number.value(count) }}</p>
+    <button :aria-label="label" @click="count++">
+      {{ increment }}
+    </button>
+  </div>
+</template>
+```
+
+`label` and `increment` are typed; a typo is a TypeScript error, a missing French value is a build error.
+
+### Lazy loading per locale
+
+**vue-i18n**
+
+```ts fileName="src/i18n.ts"
+import { nextTick } from "vue";
+import { createI18n } from "vue-i18n";
+
+export const i18n = createI18n({
+  legacy: false,
+  locale: "en",
+  fallbackLocale: "en",
+});
+
+export const loadLocaleMessages = async (locale: string) => {
+  const messages = await import(`../locales/${locale}.json`);
+  i18n.global.setLocaleMessage(locale, messages.default);
+  await nextTick();
+  i18n.global.locale.value = locale;
+};
+```
+
+Then call `loadLocaleMessages()` from a router guard, and split `locales/{locale}.json` by route yourself if you want per-page scoping.
+
+**Intlayer**
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  // ...
+  dictionary: {
+    importMode: "dynamic",
+  },
+};
+```
+
+## Keep the vue-i18n API, get Intlayer's output
+
+`@intlayer/vue-i18n` is a drop-in adapter: `useI18n()`, `t()`, `d()`, `n()`, `{name}` and `{0}` interpolation, pipe plurals (`"car | cars"`), `v-t` and `i18n.global.locale` keep working, served from Intlayer dictionaries compiled by `vite-intlayer`.
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
 ```
+
+In the benchmark, the compat build of the same app went from **134.9 KB to 47.0 KB** per page and from **196 KB to 8.4 KB** per component, with the components untouched. Your existing `locales/{locale}.json` can stay the source of truth through the JSON sync plugin.
+
+See the [vue-i18n migration guide](https://intlayer.org/doc/migration/vue-i18n) and the [compatibility doc](https://intlayer.org/doc/compatibility/vue-i18n). Nuxt users have the same path through [`@nuxtjs/i18n` compatibility](https://intlayer.org/doc/compatibility/nuxtjs-i18n).
+
+## When to choose which?
+
+- **Choose vue-i18n** if you want the standard Vue approach, you rely on ICU messages or SFC `<i18n>` blocks, you already use `@nuxtjs/i18n`, or a translation platform expects centralised JSON. Budget the time to split catalogues and lazy-load per route if bundle size matters.
+- **Choose Intlayer** if you want **component-scoped content**, **strict TypeScript**, **build-time missing-key errors**, **zero-effort tree-shaking and lazy loading**, and built-in editorial tooling (Visual Editor, CMS, AI translation, MCP server). Especially relevant for large, modular Vue / Nuxt codebases and design systems.
+- **Choose `@intlayer/vue-i18n`** if you are already on `vue-i18n` and want the bundle gains without a rewrite.
+
+## Related comparisons
+
+- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (same benchmark)
+- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer) (same benchmark)
+- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer) (same benchmark)
+- [vue-i18n vs Intlayer (features & DX)](https://intlayer.org/blog/vue-i18n-vs-intlayer)
+- [Is vue-i18n outdated?](https://intlayer.org/blog/is-vue-i18n-outdated)
+
+## 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.
+
+[![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
+
+`vue-i18n` is mature, flexible and deeply integrated with Vue. The benchmark shows what its runtime-first design costs on a Vite build: a **24 KB gzip runtime**, **134.9 KB per page** for an app that weighs 41 KB without i18n, **90% foreign-page content** on every page, and components that each reach **196 KB** because they hang off the global message tree.
+
+Intlayer moves the work into the compiler. Per-component dictionaries and dead-content purging are build outputs, not conventions. On the same app: **3.9 KB runtime**, **57.1 KB per page**, **0% page leakage**, components **25x smaller**. And if a rewrite isn't on the table, `@intlayer/vue-i18n` gets most of the way there with the components untouched.
+
+All the raw data, the test apps and the scripts are in the [Benchmark Bloom repository](https://github.com/intlayer-org/benchmark-bloom). Run it yourself.
+
+Refer to the ['Why Intlayer?' doc](https://intlayer.org/doc/why) for more details.

package/blog/es/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: Misma API, Distinto Bundle"
 description: Qué cambia cuando una aplicación React o Next.js mantiene sus llamadas a i18next, react-i18next y next-i18next pero las ejecuta a través de los adaptadores @intlayer/i18next. JavaScript por página, tamaño de componentes, fuga de strings e hidratación medidos sobre el mismo código, además de lo que los adaptadores conservan, ignoran y no pueden reemplazar.
 keywords:
@@ -28,6 +28,8 @@ author: aymericzip
 
 # i18next VS @intlayer/i18next | Misma API, Distinto 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` y `@intlayer/next-i18next` son adaptadores de compatibilidad. Exponen la API de `i18next` que tu código ya utiliza (`useTranslation`, `t()`, `<Trans>`, `i18n.changeLanguage()`, `getFixedT`, `serverSideTranslations`...) y la sirven a partir de diccionarios compilados por Intlayer. Los componentes no cambian. El runtime debajo de ellos sí.
 
 Este artículo mide ese reemplazo en la misma aplicación Next.js, construida una vez con `next-i18next` y otra con `@intlayer/next-i18next`. Las cifras proceden de [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Para comparar `i18next` e Intlayer como librerías independientes, consulta [i18next vs Intlayer](https://intlayer.org/es/blog/i18next-vs-intlayer). Este análisis se enfoca en lo que transforma el adaptador cuando mantienes tu código tal cual.
@@ -109,6 +111,10 @@ Para cada build, la suite registra:
 
 ### Resultados en Next.js
 
+Selecciona las métricas y las bibliotecas que te interesen:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Configuración                | Estrategia     | Tamaño lib (gz) | JS pág prom (gz) | Fuga idioma | Fuga pág | Comp prom (gz) | Reactividad E2E | Hidratación |
 | ---------------------------- | -------------- | --------------: | ---------------: | ----------: | -------: | -------------: | --------------: | ----------: |
 | **base** (sin i18n)          | -              |          0.0 KB |         141.0 KB |        0.0% |     0.0% |         0.9 KB |         13.4 ms |     11.8 ms |
@@ -129,10 +135,21 @@ Para cada build, la suite registra:
 - **Hidratación y cambio de idioma más rápidos.** La hidratación pasa de 15.6 ms a **11.3 ms** (y de 27.7 ms en la configuración `dynamic`, donde la petición del backend bloquea la ruta crítica). El cambio de idioma pasa de 15-16 ms a **11-12 ms**.
 - **El adaptador no es el runtime nativo.** `next-intlayer` registra **141.3 KB**, apenas +0.3 KB sobre la app base. El adaptador carga con la superficie de la API de `i18next` (sintaxis de interpolación, sufijos de plural y contexto, análisis de etiquetas `<Trans>`) sobre el núcleo de Intlayer: 9.4 KB y +9.4 KB por página respecto al nativo. Es un puente de transición, no el destino final.
 
+<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;"
+/>
+
+> Tabla completa, cada biblioteca y cada estrategia, en el [informe de benchmark de Next.js](https://intlayer.org/es/doc/benchmark/nextjs).
+
 > El adaptador `react-i18next` en Vite / TanStack Start no formó parte de esta prueba. La referencia base de `react-i18next` en TanStack Start se encuentra en [i18next vs Intlayer](https://intlayer.org/es/blog/i18next-vs-intlayer): 127-184 KB por página y 123-185 ms en el cambio de idioma cuando el backend se carga de forma diferida.
 
 ## Por qué varían las cifras
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Nada en `components/` ha cambiado, por lo que las ganancias se deben al destino al que se vincula `useTranslation`.
 
 **Con `i18next`**, la vinculación se realiza con la instancia global. Todo lo cargado en ella (todos los idiomas en `static`, el namespace entero del idioma activo en `dynamic`) resulta accesible desde cualquier componente que invoque `useTranslation()`. El empaquetador no puede dividir por debajo de lo que la instancia retiene, y el runtime no puede prever qué claves solicitará cada componente.
@@ -149,6 +166,10 @@ Nada en `components/` ha cambiado, por lo que las ganancias se deben al destino
     └── About.tsx                     # useTranslation(); t("about.title")
 ```
 
+Todo lo que contiene la instancia se envía a cada página, y el desperdicio crece en dos ejes, páginas e idiomas:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
 **Con `@intlayer/next-i18next`**, la vinculación se establece directamente con el diccionario. `syncJSON` transforma cada archivo de namespace en un diccionario; el paso de optimización proporciona al componente el diccionario requerido como una importación que el empaquetador puede rastrear y dividir por página y por idioma.
 
 ```bash
@@ -297,26 +318,112 @@ export default defineConfig({
 
 ## Límites que debes conocer antes de empezar
 
-- **Backends y detectores son inoperativos.** `i18n.use(HttpBackend)` invoca el `init` del plugin y finaliza. Si tu aplicación dependía de consultar traducciones desde un CMS en tiempo de petición, ese flujo ya no existe; utiliza el CMS de Intlayer o los comandos `intlayer pull` / `push`.
-- **`resources` se ignora, no se fusiona.** A diferencia de otros adaptadores, `@intlayer/i18next` no utiliza `resources` embebido como alternativa de rescate. Cada clave debe existir en los diccionarios sincronizados, lo que comprueba `intlayer test`.
-- **App Router requiere el cambio en el provider.** Un único archivo, mostrado arriba. Pages Router con `appWithTranslation` no necesita cambios.
-- **`next-i18next.config.js` no se lee.** `localePath`, `fallbackLng`, `reloadOnPrerender` y similares no tienen efecto; idiomas y alternativa proceden de `intlayer.config.ts`.
-- **El adaptador no es gratuito.** 9.4 KB de runtime y +9.4 KB por página respecto a `next-intlayer`. Una vez que todos tus componentes se trasladen a `useIntlayer`, elimínalo.
+<AccordionGroup>
+<Accordion header="Los backends y detectores son inertes">
+
+`i18n.use(HttpBackend)` llama al `init` del plugin y nada más. Si tu aplicación dependía de obtener traducciones de un CMS en tiempo de ejecución, ese flujo desaparece; usa el [CMS de Intlayer](https://intlayer.org/es/doc/concept/cms) o los comandos `intlayer pull` / `push` en su lugar. La detección de idioma pasa a ser la configuración de enrutamiento de Intlayer (prefijo de URL, cookie, cabecera).
+
+</Accordion>
+<Accordion header="resources se ignora, no se fusiona">
+
+A diferencia de otros adaptadores, `@intlayer/i18next` no utiliza `resources` en línea como fallback. Cada clave debe existir en los diccionarios sincronizados, lo que verifica `intlayer test`.
+
+</Accordion>
+<Accordion header="App Router necesita la edición del provider">
+
+Un solo archivo, mostrado arriba. Pages Router con `appWithTranslation` no requiere nada.
+
+</Accordion>
+<Accordion header="next-i18next.config.js no se lee">
+
+`localePath`, `fallbackLng`, `reloadOnPrerender` y similares no tienen equivalente; los idiomas y el fallback provienen de `intlayer.config.ts`.
+
+</Accordion>
+<Accordion header="El adaptador no es gratuito">
+
+9.4 KB de runtime y +9.4 KB por página respecto a `next-intlayer`. Una vez que todos los componentes hayan pasado a `useIntlayer`, elimínalo.
+
+</Accordion>
+</AccordionGroup>
 
 ## ¿Cuándo elegir cada opción?
 
-- **Quédate en `i18next`** si tu aplicación depende obligatoriamente de backends en tiempo de ejecución (traducciones servidas por un CMS al vuelo), del ecosistema de plugins, o de un entorno ajeno a React que los adaptadores no cubran.
-- **Usa `@intlayer/*`** si estás en `react-i18next` / `next-i18next` y deseas recuperar 68 KB, obtener componentes 8 veces más livianos, 0% de fuga, claves tipadas y comprobaciones en CI sin tener que reescribir tu base de código. Es el punto de partida perfecto para proyectos `i18next` consolidados.
-- **Adopta la vía nativa (`next-intlayer` / `react-intlayer`)** para proyectos nuevos o una vez que el adaptador haya cumplido su cometido. Es la opción más ligera (5.5 KB, +0.3 KB por página) y habilita Server Components síncronos y archivos `.content.ts` aislados por componente.
+<AccordionGroup>
+<Accordion header="Quédate en i18next">
+
+Tu aplicación depende de backends en tiempo de ejecución (traducciones servidas por un CMS al momento de la petición), del ecosistema de plugins o de un entorno no-React que los adaptadores no cubren.
+
+</Accordion>
+<Accordion header="Usa @intlayer/*">
+
+Estás en `react-i18next` / `next-i18next` y quieres los 68 KB, componentes 8 veces más pequeños, 0% de fuga, claves tipadas y comprobaciones de CI sin reescribir código. Este es el punto de entrada para una base de código `i18next` existente.
+
+</Accordion>
+<Accordion header="Pasa a nativo (next-intlayer / react-intlayer)">
+
+Para nuevos proyectos, o una vez que el adaptador haya cumplido su función. Tiene el runtime más ligero (5.5 KB, +0.3 KB por página) y permite Server Components síncronos y archivos `.content.ts` por componente. Comienza con [Intlayer con Next.js](https://intlayer.org/es/doc/environment/nextjs) o [con Vite y React](https://intlayer.org/es/doc/environment/vite-and-react).
+
+</Accordion>
+</AccordionGroup>
+
+## Preguntas frecuentes
+
+<FAQ>
+
+<Question title="¿De dónde provienen los 68 KB?">
+
+De `resources: { en, fr, ... }`. La configuración básica de `next-i18next` importa el JSON de cada idioma en `init()`, por lo que cada página carga cada namespace en cada idioma: **218.5 KB** por página. El adaptador nunca empaqueta ese bloque; entrega a cada componente solo el diccionario que nombra, en el idioma activo.
+
+</Question>
+
+<Question title="¿Siguen funcionando mis componentes <Trans>?">
+
+Sí, con `components`, etiquetas numeradas `<1>...</1>` y `values`. También funcionan `{{interpolation}}`, anidación `$t(key)`, plurales `key_one` / `key_other` (evaluados con `Intl.PluralRules`), sufijos de contexto y `returnObjects`.
+
+</Question>
+
+<Question title="¿Qué sucede si uso un único translation.json por idioma?">
+
+Configura `splitKeys: false` en el plugin `syncJSON`. Todo el archivo se mantiene como un único diccionario y un `useTranslation()` básico continuará resolviendo sobre él.
+
+</Question>
+
+<Question title="¿Es esto lo mismo que migrar a Intlayer?">
+
+No, es el puente. El adaptador conserva la API de `i18next` y cuesta 9.4 KB de runtime; `next-intlayer` nativo cuesta 5.5 KB y añade Server Components síncronos y archivos `.content.ts` colocados junto al código. Puedes migrar componente por componente, ya que los diccionarios JSON y `.content.ts` coexisten.
+
+</Question>
+
+<Question title="¿Pueden los traductores seguir trabajando como lo hacen hoy?">
+
+Sí. `locales/{lng}/{ns}.json` sigue siendo la fuente de verdad: `syncJSON` lo lee con el dialecto de i18next y escribe las traducciones de vuelta cuando la CLI o el CMS los actualiza.
+
+</Question>
+
+</FAQ>
 
 ## Comparativas relacionadas
 
-- [i18next vs Intlayer](https://intlayer.org/es/blog/i18next-vs-intlayer) (comparativa entre librerías, mismo benchmark)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/es/blog/next-intl-vs-intlayer-next-intl) (misma serie de adaptadores)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/es/blog/lingui-vs-intlayer-lingui) (misma serie de adaptadores)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/es/blog/vue-i18n-vs-intlayer-vue-i18n) (misma serie de adaptadores)
-- Guías de migración: [i18next](https://intlayer.org/es/doc/migration/i18next), [react-i18next](https://intlayer.org/es/doc/migration/react-i18next), [next-i18next](https://intlayer.org/es/doc/migration/next-i18next)
-- Referencias de adaptadores: [i18next](https://intlayer.org/es/doc/compatibility/i18next), [react-i18next](https://intlayer.org/es/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/es/doc/compatibility/next-i18next)
+Misma serie de adaptadores:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/es/blog/next-intl-vs-intlayer-next-intl)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/es/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/es/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+Las bibliotecas comparadas directamente:
+
+- [i18next vs Intlayer](https://intlayer.org/es/blog/i18next-vs-intlayer), same benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/es/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/es/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [Is i18next outdated?](https://intlayer.org/es/blog/is-i18next-outdated)
+
+Documentación de referencia:
+
+- Compat adapters: [i18next](https://intlayer.org/es/doc/compatibility/i18next), [react-i18next](https://intlayer.org/es/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/es/doc/compatibility/next-i18next)
+- Migration guides: [i18next](https://intlayer.org/es/doc/migration/i18next), [react-i18next](https://intlayer.org/es/doc/migration/react-i18next), [next-i18next](https://intlayer.org/es/doc/migration/next-i18next)
+- [Next.js benchmark report](https://intlayer.org/es/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/es/doc/benchmark/tanstack)
+- [Bundle optimization](https://intlayer.org/es/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/es/doc/compiler)
+- [Visual Editor](https://intlayer.org/es/doc/concept/editor), [CMS](https://intlayer.org/es/doc/concept/cms) and [AI translation](https://intlayer.org/es/doc/concept/auto-fill)
 
 ## Conclusión