Cách chọn đúng thư viện Vue i18n

"Vue i18n" vừa là một thuật ngữ chung vừa là tên của thư viện mà hầu như ai cũng cài đặt. Điều đó vừa tiện lợi vừa dễ gây hiểu lầm: vue-i18n là một lựa chọn mặc định tốt, nhưng không phải là lựa chọn duy nhất, và những câu hỏi định hình quyết định (có dùng SSR hay không, bao nhiêu trang, ai là người viết bản dịch) hiếm khi được đặt ra trước khi chạy npm install.

Hướng dẫn này sẽ đặt ra những câu hỏi đó trước, sau đó ánh xạ các câu trả lời tới những thư viện phù hợp, cho cả Vite + Vue thuần lẫn Nuxt.

Mục lục

Sáu câu hỏi cần trả lời trước khi so sánh các thư viện

1. Vite SPA hay Nuxt? Trong một SPA, chi phí catalog là vấn đề về JS bundle. Trong Nuxt, đó còn là vấn đề về HTML payload, bởi vì các message được serialize vào SSR state và hydrate. Hầu hết các báo cáo "vue-i18n chạy chậm" xuất phát từ các ứng dụng Nuxt chính vì lý do này.
2. Ai là người viết bản dịch? Developer, một TMS, một agency bàn giao chuỗi ICU, hay một AI pipeline. vue-i18n sử dụng cú pháp số nhiều riêng biệt phân cách bằng dấu gạch đứng (pipe-separated), không phải ICU. Điều này rất quan trọng nếu các chuỗi văn bản đến từ bên ngoài.
3. Có bao nhiêu locale và trang? Hai locale và năm trang có thể chuyển giao (ship) tất cả mọi thứ cùng lúc. Mười locale và bốn mươi route thì không thể, và chiến lược tải dữ liệu (loading strategy) sẽ trở thành chi phí chính.
4. Bạn có cần type trên các key không? t("cart.totl") vẫn biên dịch bình thường trong vue-i18n trừ khi bạn truyền một message schema generic, và schema đó lại xung đột với các catalog được lazy load.
5. Nội dung bao gồm những gì? Chỉ các nhãn UI, hay cả markdown, liên kết bên trong câu, và các block riêng theo từng locale. Rich content là nơi mà việc t() trả về một chuỗi string trở nên bất tiện.
6. CSP có phải là một ràng buộc không? Bản build mặc định của vue-i18n biên dịch message trong trình duyệt bằng new Function. Các bản build runtime-only cần @intlify/unplugin-vue-i18n để precompile tại thời điểm build time.

Hãy ghi lại các câu trả lời. Mọi phân tích bên dưới đều sẽ đối chiếu lại với chúng.

Bức tranh toàn cảnh qua một hình ảnh

Hệ sinh thái Vue có ít thư viện i18n hơn React, và chúng đến từ các làn sóng kiến trúc khác nhau.

Bài viết lịch sử của JavaScript i18n đi sâu chi tiết vào từng làn sóng.

Quyết định quan trọng nhất: nội dung nằm ở đâu và được tải khi nào

Hai lựa chọn mang tính cấu trúc giải thích cho hầu hết sự khác biệt về bundle size giữa các thiết lập:

• Nội dung tập trung hay phân tán theo phạm vi (scoped). Một file locales/en.json cho toàn bộ ứng dụng, hay một khai báo riêng cho từng component.
• Static hay dynamic import. Nạp tất cả mọi thứ khi khởi động, hay chỉ tải locale đang hoạt động (và lý tưởng nhất là route đang hoạt động) theo nhu cầu (on demand).

Biểu đồ ước tính payload cho một ứng dụng trên lý thuyết từ 1 đến 10 trang, được dịch sang 1 đến 10 locale, với khoảng 30 KB văn bản trên mỗi trang.

vue-i18n hỗ trợ trục dynamic: gọi setLocaleMessage sau một lệnh import() đồng nghĩa với việc bạn không còn phải chuyển giao chín locale mà không ai đọc. Điều mà nó không mang lại cho bạn là trục theo trang. Một catalog locale là một đối tượng duy nhất, và việc nạp nó sẽ nạp toàn bộ nội dung của mọi trang. Trong một SPA, không ai nhận ra điều đó. Nhưng trong Nuxt, với @nuxtjs/i18n và nhiều hơn mười trang, mỗi route đều phải gánh các chuỗi của mọi route khác hai lần: trong JS chunk và trong SSR payload.

Bài benchmark Vue đo lường điều này dưới dạng "rò rỉ từ các route khác" (leakage from other routes) và "rò rỉ từ các locale khác" (leakage from other locales). Nếu câu trả lời của bạn cho câu hỏi 3 là "nhiều trang", phần này sẽ quan trọng hơn bất kỳ sở thích API nào. Bài viết i18n theo từng component so với tập trung đề cập đến khía cạnh bảo trì của cùng sự đánh đổi này.

Các ứng cử viên

Kích thước thư viện được lấy từ bài benchmark Vue: plugin cộng với composable trong một component rỗng, sau khi bundling, tree-shaking và minification, trên một ứng dụng 10 trang, 10 locale. Nội dung được đo lường riêng biệt.

Các con số là ảnh chụp nhanh tại các phiên bản của bài benchmark. Hãy chạy thử nghiệm trên chính ứng dụng của bạn trước khi đưa ra quyết định chỉ dựa vào kích thước.

Kích thước thư viện gần như bằng 0 của Paraglide đạt được nhờ thiết kế: runtime được sinh trực tiếp vào repository của bạn, điều này đồng nghĩa với việc cần một bước sinh lại mã (regeneration) trước mỗi lần push và nguy cơ merge conflict trên các file được sinh ra. Intlayer cần vite-intlayer (hoặc Nuxt module), vì vậy nó không thể chạy nếu không có một build step.

Đối chiếu câu trả lời với thư viện phù hợp

Hạn chế của từng thư viện

• vue-i18n: nặng nhất trong nhóm, định dạng số nhiều riêng, type là tùy chọn (opt-in) và dễ vỡ khi lazy loading, không hỗ trợ phân tách phạm vi theo route, các key không dùng tích tụ một cách âm thầm. Việc để lại legacy: true trong ứng dụng Vue 3 sẽ giữ lại layer tương thích Vue 2 và làm mất khả năng gõ type của useI18n().
• @nuxtjs/i18n: thừa hưởng tất cả các nhược điểm trên, và SSR payload sẽ gánh toàn bộ chuỗi ký tự của mọi trang khi ứng dụng vượt quá khoảng một tá route.
• fluent-vue: cú pháp message tốt, không có key type, và Vite plugin nạp tất cả nội dung ở mọi ngôn ngữ vào từng trang. Nặng nhất trong bài benchmark.
• Paraglide: các file được sinh ra phải commit vào repo, cần regenerate trước mỗi lần push, và locale được đọc từ cookie hoặc storage trên mỗi lệnh gọi message thay vì từ một reactive store, làm tốn thêm tài nguyên xử lý khi chuyển đổi locale.
• Intlayer: bắt buộc phải có build plugin, hệ sinh thái nhỏ hơn, hỗ trợ ICU một phần, và nội dung phân tán khắp codebase theo thiết kế, vì vậy việc xuất ra một file JSON duy nhất cho biên dịch viên sẽ cần đến công cụ hỗ trợ.

Mã nguồn thực tế của từng lựa chọn

Cùng một component, phần tóm tắt giỏ hàng với tiêu đề và định dạng số nhiều, được viết bằng từng ứng cử viên. Điểm thú vị không nằm ở template, mà ở vị trí lưu trữ nội dung và những gì vue-tsc nhận biết được về nó.

{
  "cart": {
    "title": "Your cart",
    "items": "no item | one item | {count} items"
  }
}

<script setup lang="ts">
import { useI18n } from "vue-i18n";

const props = defineProps<{ count: number }>();
const { t } = useI18n();
</script>

<template>
  <section>
    <h2>{{ t("cart.title") }}</h2>
    <p>{{ t("cart.items", { count: props.count }, props.count) }}</p>
  </section>
</template>

cart-title = Your cart
cart-items = { $count ->
    [one] { $count } item
   *[other] { $count } items
}

<script setup lang="ts">
import { useFluent } from "fluent-vue";

const props = defineProps<{ count: number }>();
const { $t } = useFluent();
</script>

<template>
  <section>
    <h2>{{ $t("cart-title") }}</h2>
    <p>{{ $t("cart-items", { count: props.count }) }}</p>
  </section>
</template>

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

<script setup lang="ts">
import { m } from "../paraglide/messages.js";

const props = defineProps<{ count: number }>();
</script>

<template>
  <section>
    <h2>{{ m.cart_title() }}</h2>
    <p>{{ m.cart_items({ count: props.count }) }}</p>
  </section>
</template>

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({ en: "Your cart", fr: "Votre panier", es: "Tu carrito" }),
    items: t({
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

<script setup lang="ts">
import { useIntlayer } from "vue-intlayer";

const props = defineProps<{ count: number }>();
const { title, items } = useIntlayer("cart-summary");
</script>

<template>
  <section>
    <h2><title /></h2>
    <p>{{ items(props.count) }}</p>
  </section>
</template>

Bạn đang sử dụng vue-i18n? Compat adapter @intlayer/vue-i18n alias package ở cấp độ bundler, nhờ đó useI18n(), $t, pipe plural và v-t tiếp tục hoạt động trong khi Intlayer đảm nhận cung cấp nội dung. Hướng dẫn di chuyển sẽ hướng dẫn bạn cách gỡ bỏ adapter sau đó, và cũng có hướng dẫn dành riêng cho Nuxt.

Những điều cần cân nhắc trước khi quyết định

Bảng tính năng chỉ cho bạn biết một thư viện có thể làm được gì hôm nay. Những điểm dưới đây cho bạn biết trải nghiệm thực tế khi đồng hành cùng nó sẽ như thế nào.

Kiểm tra mức độ hoạt động của repository.

Các commit, thời gian phản hồi issue, và liệu bản phát hành minor gần nhất có diễn ra trong năm nay hay không. Một thiết kế hoàn hảo nhưng không có người duy trì sẽ sớm trở thành một cuộc di chuyển (migration) bắt buộc trong tương lai.

Đừng chọn thư viện chỉ dựa vào lượt tải trên npm.

Thư viện được cài đặt nhiều nhất là thư viện xuất hiện đầu tiên, không phải thư viện phù hợp nhất cho một codebase Vue năm 2026. Lượt tải phản ánh lịch sử, không phản ánh sự phù hợp.

Tìm hiểu xem ai tài trợ cho người duy trì, và họ bán sản phẩm gì.

vue-i18n được bảo trợ bởi Crowdin, tương tự như next-intl và svelte-i18n. i18next được bảo trợ bởi Locize. Tolgee, Paraglide (inlang) và Intlayer tự vận hành nền tảng riêng của mình. Một vendor có nguồn thu đến từ dịch vụ lưu trữ bản dịch (hosted translation) ít có lý do để cung cấp bản dịch miễn phí ngay bên trong chuỗi công cụ của bạn. Intlayer là thư viện duy nhất trong nhóm cung cấp tính năng dịch AI qua CLI bằng chính API key của bạn, cùng một CMS mà bạn có thể tự host.

Thư viện đã sẵn sàng cho AI-agent chưa?

Các agent vẫn còn gặp khó khăn với i18n: chúng quên locale, tự tạo key bừa bãi, và trộn lẫn các cú pháp message. Thư viện có cung cấp Agent Skills hoặc một MCP server để agent có thể liệt kê, điền và kiểm thử nội dung hay không? Và việc nạp nội dung có được tối ưu hóa theo mặc định không, hay ai đó phải xem xét lại các namespace và lazy import mỗi quý một lần?

Type safety ngay từ đầu.

Không phải "có thể gõ type nếu cấu hình thêm" mà là "sai key sẽ khiến tsc báo lỗi ngay trên một bản cài đặt mới". Hãy kiểm tra xem điều gì sẽ xảy ra khi một key không tồn tại, và khi một locale bị thiếu một bản dịch.

Phát hiện nội dung không sử dụng.

Các catalog chỉ có xu hướng phình to. Quá trình build của Intlayer sẽ loại bỏ các trường không sử dụng và ghi log chúng (build.purge). Paraglide đạt được điều này nhờ kiến trúc, vì một hàm message không được gọi sẽ bị tree-shake. Tất cả các giải pháp khác đều để lại công việc dọn dẹp cho bạn.

Trải nghiệm lập trình viên (Developer experience).

Thời gian thiết lập cho đến chuỗi dịch đầu tiên, một LSP hoặc tiện ích mở rộng VS Code hiển thị bản dịch khi hover và nhảy thẳng tới định nghĩa, một CLI để fill, test và push, cùng phương thức để người không phải developer có thể chỉnh sửa nội dung (visual editor hoặc CMS) mà không cần tạo pull request.

Câu hỏi thường gặp

Tìm hiểu thêm

• Benchmark Vue i18n: bundle size, độ rò rỉ và thời gian chuyển đổi locale
• Vue i18n: cách vue-i18n hoạt động và những điểm bất cập và bài viết về Nuxt i18n
• vue-i18n so với Intlayer, từng tính năng chi tiết và benchmark vue-i18n so với Intlayer
• vue-i18n có lỗi thời không?
• Lịch sử của JavaScript i18n
• So sánh i18n compiler và declarative
• i18n theo từng component so với tập trung
• Cài đặt i18n trong ứng dụng Vite + Vue và trong ứng dụng Nuxt
• Cùng hướng dẫn cho React, Svelte và Solid