@intlayer/docs 9.5.6 → 9.5.8

package/blog/vi/vue-i18n_vs_intlayer_benchmark.md

@@ -0,0 +1,361 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: "vue-i18n vs Intlayer: Benchmark 2026"
+description: vue-i18n và Intlayer được đo trên cùng một ứng dụng Vite + Vue 3. Kích thước thư viện, JavaScript mỗi trang, rò rỉ nội dung, kích thước component và độ phản ứng khi đổi locale, kèm giải thích các con số.
+keywords:
+  - vue-i18n
+  - Intlayer
+  - Internationalization
+  - i18n
+  - Benchmark
+  - Bundle size
+  - Blog
+  - Vue
+  - Nuxt
+  - Vite
+  - JavaScript
+slugs:
+  - blog
+  - vue-i18n-vs-intlayer-benchmark
+author: aymericzip
+---
+
+# vue-i18n VS Intlayer | Benchmark quốc tế hóa (i18n) cho Vue
+
+`vue-i18n` là thư viện i18n tham chiếu cho Vue. Intlayer là một giải pháp thay thế dựa trên trình biên dịch, nội dung được giới hạn theo component, với tích hợp Vue (`vue-intlayer`). Chúng tôi đã so sánh [tính năng và trải nghiệm lập trình viên](https://intlayer.org/blog/vue-i18n-vs-intlayer) của cả hai. Bài viết này xem xét chi phí của mỗi thư viện sau khi ứng dụng được build.
+
+Dữ liệu đến từ [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), một bộ công cụ mã nguồn mở build cùng một ứng dụng với từng thư viện và ghi lại những gì trình duyệt thực sự tải xuống và thực thi.
+
+<TOC/>
+
+> **tl;dr**: Trên cùng một ứng dụng Vite + Vue 3, `vue-i18n` gửi **134,9 KB** JavaScript nén gzip mỗi trang so với **41,3 KB** cho ứng dụng không có i18n. Intlayer gửi **57,1 KB**. Riêng runtime của `vue-i18n` đã nặng **24,3 KB gzip** (gấp 6 lần 3,9 KB của Intlayer), mỗi trang mang theo **90% chuỗi của các trang khác**, và một component được biên dịch riêng lẻ kéo theo **196 KB** vì nó bị ràng buộc với cây thông điệp toàn cục. Adapter `@intlayer/vue-i18n` giữ nguyên API của `vue-i18n` và đo được **47,0 KB** mỗi trang.
+
+## Tóm tắt
+
+- **vue-i18n** - Thư viện i18n mặc định cho Vue 2 / Vue 3 và là lõi của `@nuxtjs/i18n`. Thông điệp kiểu ICU, khối `<i18n>` trong SFC, directive `v-t`, các formatter `d()` / `n()`, hệ sinh thái lớn. Thông điệp được đăng ký trên một instance toàn cục tại `createI18n()`; lazy loading theo locale là một pattern thủ công với `setLocaleMessage()`, và việc tách theo route là do bạn tự xây dựng.
+- **Intlayer** - Mô hình nội dung lấy component làm trung tâm. Các từ điển `.content.ts` nằm cạnh component mà chúng phục vụ, một trình biên dịch lúc build (`vite-intlayer`) tree-shake và lazy-load chúng theo component và theo locale, các kiểu TypeScript nghiêm ngặt được sinh ra từ nội dung của bạn, và bản dịch thiếu sẽ gây lỗi lúc build. Đi kèm các helper cho router / SEO, Visual Editor / CMS và dịch có hỗ trợ AI.
+
+| Thư viện              | GitHub Stars                                                                                                                                                                   | Tổng số commit                                                                                                                                                                     | Commit gần nhất                                                                                                                                     | Phiên bản đầu | Phiên bản NPM                                                                                               | Lượt tải NPM                                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `aymericzip/intlayer` | [![GitHub Repo stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/aymericzip/intlayer/stargazers) | [![GitHub commit activity](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits) | [![Last Commit](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits) | Tháng 4 2024  | [![npm](https://img.shields.io/npm/v/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer) | [![npm downloads](https://img.shields.io/npm/dm/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer) |
+| `intlify/vue-i18n`    | [![GitHub Repo stars](https://img.shields.io/github/stars/intlify/vue-i18n?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/intlify/vue-i18n/stargazers)       | [![GitHub commit activity](https://img.shields.io/github/commit-activity/t/intlify/vue-i18n?style=for-the-badge&label=commits)](https://github.com/intlify/vue-i18n/commits)       | [![Last Commit](https://img.shields.io/github/last-commit/intlify/vue-i18n?style=for-the-badge)](https://github.com/intlify/vue-i18n/commits)       | Tháng 12 2016 | [![npm](https://img.shields.io/npm/v/vue-i18n?style=for-the-badge)](https://www.npmjs.com/package/vue-i18n) | [![npm downloads](https://img.shields.io/npm/dm/vue-i18n?style=for-the-badge)](https://www.npmjs.com/package/vue-i18n) |
+
+> Các huy hiệu tự động cập nhật. Ảnh chụp sẽ thay đổi theo thời gian.
+
+## So sánh tính năng song song
+
+| Tính năng                                     | `vue-intlayer` (Intlayer)                                   | `vue-i18n`                                                                       |
+| --------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| **Bản dịch gần component**                    | ✅ Có, `.content.ts` đặt cùng chỗ với mỗi component         | ✅ Qua khối SFC `<i18n>` (tùy chọn); catalog toàn cục là cách thiết lập phổ biến |
+| **Tích hợp TypeScript**                       | ✅ Kiểu nghiêm ngặt tự động sinh từ nội dung                | ✅ Typing tốt; an toàn khóa nghiêm ngặt cần typing schema và kỷ luật             |
+| **Phát hiện bản dịch thiếu**                  | ✅ Lỗi TypeScript + lỗi/cảnh báo lúc build                  | ⚠️ Fallback lúc runtime + cảnh báo console                                       |
+| **Nội dung phong phú (component / Markdown)** | ✅ Hỗ trợ trực tiếp                                         | ⚠️ Nội suy component `<i18n-t>`; Markdown qua plugin bên ngoài                   |
+| **Hỗ trợ ICU**                                | ⚠️ Đang phát triển                                          | ✅ Có                                                                            |
+| **Định dạng (ngày, số, tiền tệ)**             | ✅ Formatter dựa trên Intl                                  | ✅ `d()` / `n()` với `datetimeFormats` / `numberFormats`                         |
+| **Routing bản địa hóa**                       | ✅ Helper cho Vue Router / Nuxt, `getMultilingualUrls`      | ⚠️ Không phải lõi (`@nuxtjs/i18n` hoặc thiết lập router tùy chỉnh)               |
+| **Helper SEO (hreflang, sitemap, robots)**    | ✅ Helper tích hợp sẵn                                      | ❌ Không phải lõi                                                                |
+| **Tree-shaking (chỉ gửi nội dung được dùng)** | ✅ Theo component, theo locale, tự động bởi trình biên dịch | ⚠️ Thủ công: tách catalog, `setLocaleMessage()` theo route                       |
+| **Lazy loading**                              | ✅ `importMode: 'dynamic'` (một dòng cấu hình)              | ✅ `import()` thủ công + `setLocaleMessage()`                                    |
+| **Loại bỏ nội dung không dùng**               | ✅ Từ điển không dùng bị loại bỏ lúc build                  | ❌ Không tích hợp sẵn                                                            |
+| **Kiểm tra bản dịch thiếu (CLI / CI)**        | ✅ `npx intlayer content test`                              | ⚠️ Bên thứ ba (`vue-i18n-extract`)                                               |
+| **Dịch bằng AI**                              | ✅ Tích hợp sẵn, dùng khóa nhà cung cấp của riêng bạn       | ❌ Không                                                                         |
+| **Visual Editor / CMS**                       | ✅ Visual Editor miễn phí + CMS tùy chọn                    | ❌ Không (nền tảng bản địa hóa bên ngoài)                                        |
+| **MCP server & Agent Skills**                 | ✅ Có                                                       | ❌ Không                                                                         |
+| **Hệ sinh thái / cộng đồng**                  | ⚠️ Nhỏ hơn nhưng đang phát triển nhanh                      | ✅ Lớn và trưởng thành trong hệ sinh thái Vue                                    |
+
+## Benchmark
+
+### Những gì được đo
+
+Bộ [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) build **cùng một ứng dụng Vite + Vue 3** với từng thư viện: **10 trang** (home, about, blog, careers, contact, FAQ, pricing, products, settings, team), **10 locale** (`en`, `fr`, `es`, `de`, `it`, `pt`, `zh`, `ja`, `ko`, `ru`), component giống hệt và nội dung giống hệt. Các trang được đo ở `en` và `fr`.
+
+Cả hai thư viện được kiểm thử ở cấu hình **static**, cấu hình mà hầu hết dự án Vue triển khai: với `vue-i18n`, JSON của mọi locale được import và truyền vào `createI18n({ messages })`; với Intlayer, `importMode: 'static'` mặc định. Ở chế độ đó Intlayer cũng đóng gói mọi locale, nhưng trình biên dịch vẫn giới hạn nội dung **theo component**, nên một trang chỉ mang theo từ điển của các component mà nó render.
+
+Với mỗi bản build, bộ công cụ ghi lại:
+
+- **Lib size**: kích thước gzip của một component rỗng chỉ import thư viện i18n. Chi phí cố định của runtime.
+- **Page JS**: JavaScript gzip tải xuống mỗi trang, tính trung bình trên tất cả các trang và locale.
+- **Locale leak %**: tỷ lệ chuỗi đã dịch tìm thấy trong JS tải xuống thuộc về một locale mà người dùng **không** đang xem (lấy dấu vân tay trên `en` và `fr`, nên 50% nghĩa là "locale được đo còn lại hiện diện đầy đủ"; với 10 locale được đóng gói, lãng phí thực tế còn cao hơn).
+- **Page leak %**: tỷ lệ chuỗi đã dịch tìm thấy trong JS tải xuống thuộc về một trang mà người dùng **không** đang ở.
+- **Component avg**: kích thước gzip trung bình của mỗi component được biên dịch riêng lẻ. Cho thấy một component đơn lẻ kéo theo bao nhiêu runtime i18n và catalog.
+- **E2E reactivity**: thời gian thực từ lúc chọn locale mới đến khi `html[lang]` được cập nhật trong DOM (Playwright, 5 lần lặp).
+- **Page load**: `PerformanceNavigationTiming.duration`.
+
+> Các con số dưới đây đến từ lần chạy ngày **2026-09-12** với `vue-i18n` 11.4.0 và `intlayer` 9.5.0 / 9.5.1. Ứng dụng kiểm thử được cố ý làm nhỏ (vài chục chuỗi mỗi locale), nên tỷ lệ rò rỉ mô tả một **mẫu hình**: chúng tăng theo nội dung của bạn trong khi chi phí runtime giữ nguyên.
+
+### Kết quả trên Vite + Vue 3
+
+| Thư viện                      | Chiến lược | Lib size (gz) | Lib size (min) | Page JS TB (gz) | Locale leak | Page leak | Component TB (gz) | Phản ứng E2E | Page load |
+| ----------------------------- | ---------- | ------------: | -------------: | --------------: | ----------: | --------: | ----------------: | -----------: | --------: |
+| **base** (không i18n)         | -          |        0,0 KB |         0,0 KB |         41,3 KB |        0,0% |         - |            1,1 KB |       1,8 ms |   10,8 ms |
+| `vue-i18n`                    | static     |       24,3 KB |        83,2 KB |        134,9 KB |       50,0% |     90,0% |          196,0 KB |       2,8 ms |   13,6 ms |
+| **`vue-intlayer`**            | static     |    **3,9 KB** |    **11,1 KB** |     **57,1 KB** |       56,8% |  **0,0%** |        **7,7 KB** |   **4,5 ms** |   13,8 ms |
+| `@intlayer/vue-i18n` (compat) | static     |        7,9 KB |        23,2 KB |         47,0 KB |       15,0% |      0,0% |            8,4 KB |       1,5 ms |    9,3 ms |
+
+> Cột page-leak của ứng dụng base được để trống: không có thư viện i18n, việc lấy dấu vân tay bắt được các chuỗi hard-code trong các chunk dùng chung và con số không có ý nghĩa.
+
+**Cách đọc**
+
+- **Chi phí runtime.** `vue-i18n` là một trong những runtime nặng nhất toàn bộ benchmark: **24,3 KB gzip / 83,2 KB minified** cho một component rỗng chỉ import nó. `vue-intlayer` tốn 3,9 KB gzip. Khoảng cách đó phải trả trên mọi trang bất kể bạn có bao nhiêu chuỗi.
+- **JavaScript mỗi trang.** Ứng dụng không có i18n nặng 41,3 KB. `vue-i18n` tăng gấp hơn ba lần lên **134,9 KB**; Intlayer dừng ở **57,1 KB**, +15,8 KB, phần lớn là mười locale được đóng gói (xem điểm tiếp theo).
+- **Rò rỉ.** Với `createI18n({ messages: { en, fr, ... } })`, mọi trang gửi mọi locale và chuỗi của mọi trang: **50% rò rỉ locale** (trên hai locale được lấy dấu vân tay) và **90% rò rỉ trang**. Chế độ `static` của Intlayer cũng đóng gói mọi locale (do đó con số rò rỉ locale tương đương) nhưng có **0% rò rỉ trang**: một trang chỉ kéo từ điển của các component mà nó render. Chuyển sang `importMode: 'dynamic'` loại bỏ luôn rò rỉ locale; cấu hình đó không nằm trong lần chạy Vue này.
+- **Kích thước component là nơi kiến trúc thể hiện rõ.** Một component gọi `useI18n()` biên dịch trung bình ra **196 KB**, vì `t()` bị ràng buộc với instance toàn cục chứa mọi thông điệp của mọi locale. Cùng component đó với `useIntlayer()` biên dịch ra **7,7 KB**: nó chỉ chạm tới từ điển của chính nó.
+- **Độ phản ứng** không phải vấn đề với cả hai (2-5 ms). Hệ thống reactivity của Vue khiến việc đổi locale rất rẻ một khi thông điệp đã ở trong bộ nhớ.
+- **`@intlayer/vue-i18n`**, adapter drop-in, giữ nguyên API của `vue-i18n` và đo được **47,0 KB mỗi trang** và **8,4 KB mỗi component**, với mã ứng dụng không thay đổi.
+
+> Để tham khảo, cùng lần chạy đó đo `fluent-vue` ở mức 171,8 KB mỗi trang, 29,7 KB runtime và 217 KB mỗi component.
+
+## Tại sao có khoảng cách? Instance toàn cục vs từ điển được biên dịch
+
+`vue-i18n` là một runtime. `createI18n()` xây dựng một instance toàn cục chứa cây thông điệp cho mỗi locale; `useI18n()` ràng buộc mỗi component với nó; `t("footer.github")` tra khóa lúc render. Đây là điều giúp khối SFC `<i18n>`, `v-t` và tải thông điệp lúc runtime trở nên khả thi, và cũng là lý do đồ thị phụ thuộc của mọi component bao gồm toàn bộ cây:
+
+```bash
+.
+├── locales
+│   ├── en.json
+│   ├── fr.json
+│   └── ...                        # một file mỗi locale, tất cả các trang bên trong
+└── src
+    ├── i18n.ts                    # createI18n({ messages: { en, fr, ... } })
+    ├── main.ts
+    └── components
+        └── Footer.vue             # const { t } = useI18n(); t("footer.github")
+```
+
+Tối ưu hóa nghĩa là **bạn** tách `en.json` thành các file theo route, **bạn** gọi `setLocaleMessage()` trong một router guard, và **bạn** giữ cho ánh xạ route-file luôn đúng khi component di chuyển. Runtime không thể làm điều đó cho bạn vì nó không biết component sẽ yêu cầu khóa nào.
+
+Intlayer chuyển kiến thức đó sang lúc build. Nội dung được khai báo cạnh component, và `vite-intlayer` phân giải component nào import từ điển nào:
+
+```bash
+.
+├── intlayer.config.ts
+└── src
+    ├── main.ts                    # createApp(App).use(intlayer)
+    └── components
+        └── Footer
+            ├── Footer.vue         # useIntlayer("footer")
+            └── Footer.content.ts
+```
+
+Trình biên dịch xuất ra, theo từng từ điển và từng locale, chính xác JSON mà component đó cần, và loại bỏ các từ điển không được import ở đâu cả. Giới hạn theo route là hệ quả của giới hạn theo component, không phải một nhiệm vụ.
+
+> Để loại bỏ luôn các locale không dùng, đặt `dictionary.importMode: 'dynamic'` trong `intlayer.config.ts`. Xem [tài liệu tối ưu bundle](https://intlayer.org/doc/concept/bundle-optimization).
+
+## Trải nghiệm lập trình viên
+
+### Thiết lập
+
+**vue-i18n**
+
+```ts fileName="src/i18n.ts"
+import { createI18n } from "vue-i18n";
+import en from "../locales/en.json";
+import fr from "../locales/fr.json";
+
+export const i18n = createI18n({
+  legacy: false,
+  locale: "en",
+  fallbackLocale: "en",
+  messages: { en, fr },
+});
+```
+
+```ts fileName="src/main.ts"
+import { createApp } from "vue";
+import App from "./App.vue";
+import router from "./router";
+import { i18n } from "./i18n";
+
+createApp(App).use(router).use(i18n).mount("#app");
+```
+
+**Intlayer**
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer(), vue()],
+});
+```
+
+```ts fileName="src/main.ts"
+import { createApp } from "vue";
+import { intlayer } from "vue-intlayer";
+import App from "./App.vue";
+import router from "./router";
+
+createApp(App).use(intlayer).use(router).mount("#app");
+```
+
+### Component
+
+**vue-i18n**
+
+```json fileName="locales/en.json"
+{
+  "counter": {
+    "label": "Counter",
+    "increment": "Increment"
+  }
+}
+```
+
+```vue fileName="src/components/Counter.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { useI18n } from "vue-i18n";
+
+const { t, n } = useI18n();
+const count = ref(0);
+</script>
+
+<template>
+  <div>
+    <p>{{ n(count) }}</p>
+    <button :aria-label="t('counter.label')" @click="count++">
+      {{ t("counter.increment") }}
+    </button>
+  </div>
+</template>
+```
+
+`t('counter.label')` chỉ là một chuỗi cho đến khi bạn tự định kiểu schema thông điệp; một lỗi gõ sẽ render ra khóa.
+
+**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` và `increment` có kiểu; một lỗi gõ là lỗi TypeScript, thiếu giá trị tiếng Pháp là lỗi build.
+
+### Lazy loading theo 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;
+};
+```
+
+Sau đó gọi `loadLocaleMessages()` từ một router guard, và tự tách `locales/{locale}.json` theo route nếu bạn muốn giới hạn theo trang.
+
+**Intlayer**
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  // ...
+  dictionary: {
+    importMode: "dynamic",
+  },
+};
+```
+
+## Giữ API của vue-i18n, nhận đầu ra của Intlayer
+
+`@intlayer/vue-i18n` là một adapter drop-in: `useI18n()`, `t()`, `d()`, `n()`, nội suy `{name}` và `{0}`, số nhiều dạng pipe (`"car | cars"`), `v-t` và `i18n.global.locale` vẫn hoạt động, được phục vụ từ các từ điển Intlayer do `vite-intlayer` biên dịch.
+
+```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()],
+});
+```
+
+Trong benchmark, bản build compat của cùng ứng dụng giảm từ **134,9 KB xuống 47,0 KB** mỗi trang và từ **196 KB xuống 8,4 KB** mỗi component, với các component không thay đổi. Các file `locales/{locale}.json` hiện có của bạn có thể tiếp tục là nguồn sự thật thông qua plugin đồng bộ JSON.
+
+Xem [hướng dẫn di chuyển từ vue-i18n](https://intlayer.org/doc/migration/vue-i18n) và [tài liệu tương thích](https://intlayer.org/doc/compatibility/vue-i18n). Người dùng Nuxt có cùng lộ trình qua [tương thích `@nuxtjs/i18n`](https://intlayer.org/doc/compatibility/nuxtjs-i18n).
+
+## Khi nào chọn cái nào?
+
+- **Chọn vue-i18n** nếu bạn muốn cách tiếp cận Vue tiêu chuẩn, bạn dựa vào thông điệp ICU hoặc khối SFC `<i18n>`, bạn đã dùng `@nuxtjs/i18n`, hoặc một nền tảng dịch thuật yêu cầu JSON tập trung. Hãy dành thời gian tách catalog và lazy-load theo route nếu kích thước bundle quan trọng.
+- **Chọn Intlayer** nếu bạn muốn **nội dung giới hạn theo component**, **TypeScript nghiêm ngặt**, **lỗi thiếu khóa lúc build**, **tree-shaking và lazy loading không tốn công**, và công cụ biên tập tích hợp sẵn (Visual Editor, CMS, dịch AI, MCP server). Đặc biệt phù hợp với các codebase Vue / Nuxt lớn, mô-đun hóa và các design system.
+- **Chọn `@intlayer/vue-i18n`** nếu bạn đã dùng `vue-i18n` và muốn lợi ích về bundle mà không cần viết lại.
+
+## Các so sánh liên quan
+
+- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (cùng benchmark)
+- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer) (cùng benchmark)
+- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer) (cùng benchmark)
+- [vue-i18n vs Intlayer (tính năng & DX)](https://intlayer.org/blog/vue-i18n-vs-intlayer)
+- [vue-i18n đã lỗi thời?](https://intlayer.org/blog/is-vue-i18n-outdated)
+
+## GitHub Stars
+
+GitHub stars là chỉ báo mạnh về mức độ phổ biến của một dự án, sự tin tưởng của cộng đồng và tính phù hợp lâu dài. Dù không phải thước đo trực tiếp về chất lượng kỹ thuật, chúng phản ánh có bao nhiêu lập trình viên thấy dự án hữu ích, theo dõi tiến trình của nó và có khả năng áp dụng.
+
+[![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)
+
+## Kết luận
+
+`vue-i18n` trưởng thành, linh hoạt và tích hợp sâu với Vue. Benchmark cho thấy thiết kế ưu tiên runtime của nó tốn gì trên một bản build Vite: **runtime 24 KB gzip**, **134,9 KB mỗi trang** cho một ứng dụng chỉ nặng 41 KB khi không có i18n, **90% nội dung của trang khác** trên mọi trang, và các component mỗi cái lên tới **196 KB** vì chúng treo trên cây thông điệp toàn cục.
+
+Intlayer chuyển công việc vào trình biên dịch. Từ điển theo component và loại bỏ nội dung chết là đầu ra của build, không phải quy ước. Trên cùng ứng dụng: **runtime 3,9 KB**, **57,1 KB mỗi trang**, **0% rò rỉ trang**, component **nhỏ hơn 25 lần**. Và nếu việc viết lại không khả thi, `@intlayer/vue-i18n` đi được phần lớn chặng đường mà không đụng đến component.
+
+Toàn bộ dữ liệu thô, ứng dụng kiểm thử và script nằm trong [kho lưu trữ Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Hãy tự chạy thử.
+
+Tham khảo [tài liệu 'Tại sao Intlayer?'](https://intlayer.org/doc/why) để biết thêm chi tiết.

package/blog/zh/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：相同的 API，截然不同的 Bundle"
 description: 当 React 或 Next.js 应用保持其 i18next、react-i18next 和 next-i18next 调用不变，但改由 @intlayer/i18next 适配器提供服务时会发生什么变化。基于同一套代码测量的每页 JavaScript 体积、组件大小、文本泄漏与水合性能，以及适配器保留、忽略和无法替代的功能。
 keywords:
@@ -28,6 +28,8 @@ author: aymericzip
 
 # i18next VS @intlayer/i18next | 相同的 API，截然不同的 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` 和 `@intlayer/next-i18next` 是兼容适配器。它们暴露了你的代码已经在使用的 `i18next` API（`useTranslation`、`t()`、`<Trans>`、`i18n.changeLanguage()`、`getFixedT`、`serverSideTranslations` 等），并通过 Intlayer 编译好的字典来提供数据。组件不需要做任何更改，只是其底层的运行时发生了改变。
 
 本文在同一个 Next.js 应用程序上对比了这种替换：一次使用 `next-i18next` 构建，另一次使用 `@intlayer/next-i18next` 构建。测试数据来源于 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)。如需对比作为独立库的 `i18next` 与 Intlayer，请阅读 [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-vs-intlayer)。本文则专注于：当你保持原有代码不变时，适配器带来了哪些实际变化。
@@ -109,6 +111,10 @@ const About = () => {
 
 ### Next.js 平台对比数据
 
+选择您关注的指标和库：
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 方案                         | 加载策略       | Lib 体积 (gz) | 每页 JS 均值 (gz) | 语言泄漏率 | 跨页泄漏率 | 组件均值 (gz) | E2E 响应耗时 |    水合耗时 |
 | ---------------------------- | -------------- | ------------: | ----------------: | ---------: | ---------: | ------------: | -----------: | ----------: |
 | **base** (无 i18n)           | -              |        0.0 KB |          141.0 KB |       0.0% |       0.0% |        0.9 KB |      13.4 ms |     11.8 ms |
@@ -129,10 +135,21 @@ const About = () => {
 - **更迅捷的水合与语言切换。** 水合耗时从 15.6 ms 降至 **11.3 ms**（对比 `dynamic` 方案中后端请求阻塞关键渲染路径导致的 27.7 ms 提升尤为显著）。语言实时切换耗时也从 15-16 ms 缩减至 **11-12 ms**。
 - **适配器不等于原生极致架构。** 原生的 `next-intlayer` 仅有 **141.3 KB**，仅比无任何国际化逻辑的基础应用多了 0.3 KB。适配器为了维持 `i18next` API 的兼容性（插值语法、复数与上下文后缀解析、`<Trans>` 标签树解析），在 Intlayer 核心之上保留了一层 9.4 KB 的兼容垫片。它是迈向现代化的无缝桥梁，而非终点。
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 完整表格、各个库及每种策略，请参阅 [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs)。
+
 > 本次评测暂未包含 Vite / TanStack Start 上的 `react-i18next` 适配器。有关 TanStack Start 的基准表现可参考 [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-vs-intlayer)：每页 127-184 KB，后端异步加载下的语言切换延迟约为 123-185 ms。
 
 ## 性能巨幅提升的底层机理
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 业务 `components/` 目录没有改动一行代码，所有性能收益完全归结于 `useTranslation` 到底绑定在什么载体上。
 
 **在 `i18next` 中**，组件必须挂载到全局实例上。凡是预加载进该实例的内容（`static` 下的全部语种，或 `dynamic` 下当前语种的全部字典），都能被任何一个调用 `useTranslation()` 的组件直接访问。打包工具无法对实例内部的数据进行细粒度拆分，运行时也无法预知组件渲染时会访问哪些键名。
@@ -149,6 +166,10 @@ const About = () => {
     └── About.tsx                     # useTranslation(); t("about.title")
 ```
 
+实例中包含的任何内容都会发送到每个页面，浪费在页面和语言两个维度上不断增长：
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
 **在 `@intlayer/next-i18next` 中**，组件直接与精简字典绑定。`syncJSON` 将每个命名空间文件解析并独立封装为字典；编译优化通道将组件精准重定向为对其声明字典的直接导入，这让打包工具能够像处理普通 JS 模块一样，按照页面和语言维度进行 Tree-shaking 与按需代码分割。
 
 ```bash
@@ -297,26 +318,112 @@ export default defineConfig({
 
 ## 启动迁移前必须明确的技术边界
 
-- **运行时后端与动态探测器将不再生效。** `i18n.use(HttpBackend)` 仅会执行插件基础初始化，并不会在页面访问时动态拉取外部翻译接口。如果原应用依赖于请求发生时由 CMS 动态返回翻译，建议切换至 Intlayer 官方 CMS 或使用 `intlayer pull` / `push` 指令。
-- **`resources` 参数被忽略而非智能合并。** 与部分轻度包装器不同，`@intlayer/i18next` 不会将内联的 `resources` 作为降级兜底方案。每一个键都必须真实存在于同步好的本地字典中（可通过 `intlayer test` 校验）。
-- **App Router 需要且仅需要修改一次 Provider。** 即上述所示的一处微调。若采用 Pages Router 搭配 `appWithTranslation`，则连这处都不需要修改。
-- **`next-i18next.config.js` 会被彻底跳过。** 原有的 `localePath`、`fallbackLng`、`reloadOnPrerender` 等选项不再生效；所有相关逻辑统一迁移至 `intlayer.config.ts`。
-- **适配器自身具备少量固定体积。** 包含 9.4 KB 的运行时以及相比原生 `next-intlayer` 每页多出 9.4 KB。当项目所有组件都逐步平移至原生的 `useIntlayer` 后，即可直接卸载适配器。
+<AccordionGroup>
+<Accordion header="后端和检测器不生效">
+
+`i18n.use(HttpBackend)` 仅调用插件的 init，不执行其他任何操作。如果您的应用依赖于在运行时从 CMS 获取翻译，该流程已不复存在；请改用 [Intlayer CMS](https://intlayer.org/zh/doc/concept/cms) 或 `intlayer pull` / `push` 命令。语言检测由 Intlayer 的路由配置接管（URL 前缀、cookie、请求头）。
+
+</Accordion>
+<Accordion header="resources 被忽略，不进行合并">
+
+与其他一些适配器不同，`@intlayer/i18next` 不使用内联 `resources` 作为回退。每个键必须存在于同步的字典中，`intlayer test` 会对此进行验证。
+
+</Accordion>
+<Accordion header="App Router 需要修改 provider">
+
+仅需修改一个文件，如上所示。使用 `appWithTranslation` 的 Pages Router 无需任何更改。
+
+</Accordion>
+<Accordion header="不读取 next-i18next.config.js">
+
+`localePath`、`fallbackLng`、`reloadOnPrerender` 等配置项均无对应项；语言和回退语言均来自 `intlayer.config.ts`。
+
+</Accordion>
+<Accordion header="适配器并非完全零成本">
+
+相比 `next-intlayer`，它增加了 9.4 KB 的运行时以及每页 +9.4 KB 的体积。一旦所有组件都迁移到 `useIntlayer`，即可将其移除。
+
+</Accordion>
+</AccordionGroup>
 
 ## 选型决策指南
 
-- **继续坚守 `i18next` 原生方案**：如果你的系统高度依赖运行时接口后端（即每次请求必须动态拉取 CMS 最新内容）、强依赖特定三方插件生态，或者属于适配器尚未覆盖的非 React 运行时环境。
-- **全面接入 `@intlayer/*` 兼容适配器**：如果你正在使用 `react-i18next` / `next-i18next`，希望在零业务代码重写的条件下立刻获得 68 KB 减重、8 倍更小的轻量组件、0% 文本泄漏、类型安全保障和 CI 自动化。这是既有 `i18next` 项目的最佳渐进式改造路径。
-- **拥抱原生纯血架构 (`next-intlayer` / `react-intlayer`)**：适合全新启动的项目，或者已经通过适配器平稳完成过渡的团队。它拥有无与伦比的超轻量表现（5.5 KB，每页仅增加 0.3 KB），并彻底解锁同步 Server Components 与组件级 `.content.ts` 同构体验。
+<AccordionGroup>
+<Accordion header="继续使用 i18next">
+
+您的应用依赖于运行时后端（在请求时由 CMS 提供的翻译）、插件生态系统，或者适配器未涵盖的非 React 目标环境。
+
+</Accordion>
+<Accordion header="使用 @intlayer/*">
+
+您正在使用 `react-i18next` / `next-i18next`，希望在无需重写代码的前提下节省 68 KB、实现组件体积缩小 8 倍、0% 泄漏、类型化键和 CI 检查。这是现有 `i18next` 代码库的最佳过渡方案。
+
+</Accordion>
+<Accordion header="转向原生 (next-intlayer / react-intlayer)">
+
+适用于新项目，或在适配器完成过渡任务之后。它具有最轻量的运行时（5.5 KB，每页仅增加 0.3 KB），并解锁同步 Server Components 和按组件划分的 `.content.ts` 文件。请从 [Intlayer 与 Next.js](https://intlayer.org/zh/doc/environment/nextjs) 或 [与 Vite 和 React](https://intlayer.org/zh/doc/environment/vite-and-react) 开始。
+
+</Accordion>
+</AccordionGroup>
+
+## 常见问题解答
+
+<FAQ>
+
+<Question title="68 KB 的体积节省来自哪里？">
+
+来自 `resources: { en, fr, ... }`。原生的 `next-i18next` 配置会在 `init()` 中导入每种语言的全部 JSON，因此每个页面都携带所有语言的每个命名空间：每页达到 **218.5 KB**。适配器从不打包整个区块；它仅在当前激活的语言下向每个组件提供其声明的字典。
+
+</Question>
+
+<Question title="我的 <Trans> 组件还能正常工作吗？">
+
+可以，完全支持 `components`、数字标签 `<1>...</1>` 以及 `values`。同时支持 `{{interpolation}}`、`$t(key)` 嵌套、`key_one` / `key_other` 复数（由 `Intl.PluralRules` 计算）、上下文后缀以及 `returnObjects`。
+
+</Question>
+
+<Question title="如果我每种语言只使用一个 translation.json 怎么办？">
+
+在 `syncJSON` 插件中设置 `splitKeys: false`。整个文件将保持为一个字典，普通的 `useTranslation()` 会继续针对其进行解析。
+
+</Question>
+
+<Question title="这是否等同于直接迁移到 Intlayer？">
+
+不等同，它是过渡桥梁。适配器保留了 `i18next` 的 API，运行时开销为 9.4 KB；原生 `next-intlayer` 仅需 5.5 KB，并带来同步 Server Components 和同级放置的 `.content.ts` 文件。由于 JSON 和 `.content.ts` 字典可以并存，您可以逐个组件推进迁移。
+
+</Question>
+
+<Question title="翻译人员是否能沿用目前的工作流程？">
+
+可以。`locales/{lng}/{ns}.json` 依然是唯一事实来源：`syncJSON` 以 i18next 方言读取它，并在 CLI 或 CMS 更新时将翻译写回。
+
+</Question>
+
+</FAQ>
 
 ## 相关对比与进阶文档
 
-- [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-vs-intlayer)（库级别深度全方位基准测试）
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/zh/blog/next-intl-vs-intlayer-next-intl)（同系列适配器测评）
-- [Lingui vs @intlayer/lingui](https://intlayer.org/zh/blog/lingui-vs-intlayer-lingui)（同系列适配器测评）
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-vue-i18n)（同系列适配器测评）
-- 迁移指引：[i18next](https://intlayer.org/zh/doc/migration/i18next), [react-i18next](https://intlayer.org/zh/doc/migration/react-i18next), [next-i18next](https://intlayer.org/zh/doc/migration/next-i18next)
-- 适配器技术规范：[i18next](https://intlayer.org/zh/doc/compatibility/i18next), [react-i18next](https://intlayer.org/zh/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/zh/doc/compatibility/next-i18next)
+同系列适配器：
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/zh/blog/next-intl-vs-intlayer-next-intl)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/zh/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+两两直接对比：
+
+- [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-vs-intlayer), same benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/zh/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/zh/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [Is i18next outdated?](https://intlayer.org/zh/blog/is-i18next-outdated)
+
+参考文档：
+
+- Compat adapters: [i18next](https://intlayer.org/zh/doc/compatibility/i18next), [react-i18next](https://intlayer.org/zh/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/zh/doc/compatibility/next-i18next)
+- Migration guides: [i18next](https://intlayer.org/zh/doc/migration/i18next), [react-i18next](https://intlayer.org/zh/doc/migration/react-i18next), [next-i18next](https://intlayer.org/zh/doc/migration/next-i18next)
+- [Next.js benchmark report](https://intlayer.org/zh/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/zh/doc/benchmark/tanstack)
+- [Bundle optimization](https://intlayer.org/zh/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/zh/doc/compiler)
+- [Visual Editor](https://intlayer.org/zh/doc/concept/editor), [CMS](https://intlayer.org/zh/doc/concept/cms) and [AI translation](https://intlayer.org/zh/doc/concept/auto-fill)
 
 ## 总结