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

React không đi kèm primitive i18n nào. Thư viện bạn chọn ngay từ ngày đầu tiên sẽ quyết định cách các bản dịch được lưu trữ, cách chúng được nạp vào bundle, và bạn sẽ phải tự xử lý bao nhiêu công việc trong vài năm tiếp theo. Hầu hết các đội ngũ lựa chọn dựa trên mức độ phổ biến, rồi sau đó mới nhận ra sự đánh đổi khi ứng dụng chạm mốc 2.000 key.

Hướng dẫn này tiếp cận theo hướng ngược lại: hãy trả lời vài câu hỏi về dự án của bạn trước, sau đó đối chiếu các câu trả lời với những thư viện phù hợp. Hướng dẫn tập trung vào React thuần (Vite, React Router, TanStack Start). Next.js có những ràng buộc riêng, được đề cập trong bài so sánh Next.js.

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

Bảng so sánh tính năng sẽ vô nghĩa nếu bạn không biết tiêu chí nào thực sự quan trọng với mình. Hãy xem xét các câu hỏi này trước.

1. Ứng dụng được render như thế nào? Chỉ SPA, SSR kèm hydration, hay React Server Components. Các hook dựa trên Context hoạt động ở mọi nơi trong SPA. Với RSC, một hook sẽ buộc mọi component render văn bản phải dùng "use client", vì vậy bạn cũng sẽ cần một API phía server.
2. Ai là người viết bản dịch? Developer, đội ngũ nội bộ dùng TMS, agency bàn giao file ICU, hay một AI pipeline. Yếu tố này quyết định định dạng catalog nhiều hơn bất kỳ chi tiết API nào.
3. Có bao nhiêu locale và trang? Hai locale và năm trang có thể nạp toàn bộ nội dung cùng lúc. Nhưng mười locale và năm 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 cho các key không? Lỗi chính tả trong t("checkout.totl") vẫn biên dịch bình thường trong mọi thư viện dùng key trừ khi bạn tự cấu hình type. Hãy quyết định xem điều đó có chấp nhận được hay không.
5. Chuỗi chứa những nội dung gì? Văn bản thuần túy, số nhiều (plurals), hay các câu có chèn <Link> ở giữa. Rich content chính là nơi mà hầu hết các API trở nên cồng kềnh.
6. Vòng đời dự án kéo dài bao lâu? Một bản prototype ba tháng và một sản phẩm phát triển năm năm không cần cùng một mức độ công cụ build (build tooling).

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

Mười lăm năm phát triển của JavaScript i18n gói gọn trong bốn làn sóng kiến trúc, và các thư viện React bạn đang so sánh đến từ những làn sóng khác nhau.

Bài viết lịch sử JavaScript i18n giải thích chi tiết cách mỗi làn sóng giải quyết các vấn đề của làn sóng trước đó.

Quyết định quan trọng nhất: nơi lưu trữ nội dung và thời điểm tải

Mọi thư viện React i18n đều có cấu trúc tương tự nhau: một store, một provider, một hook. Bất kể thứ gì provider nhận vào đều sẽ nằm trong client bundle hoặc trong hydration payload. Vì vậy, hai lựa chọn mang tính cấu trúc là:

• Nội dung tập trung (centralized) hay phân phạm vi (scoped). Một file en.json cho toàn bộ ứng dụng, hoặc một file khai báo riêng cho từng component (hoặc theo namespace).
• Static import hay dynamic import. Toàn bộ được đóng gói ngay khi khởi động, hoặc chỉ tải locale và route đang hoạt động theo nhu cầu.

Biểu đồ dưới đây ước tính payload cho một ứng dụng giả định 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.

Nội dung tập trung với static import sẽ tăng theo cả hai trục: 10 trang nhân với 10 locale là 300 KB văn bản trên mỗi trang. Dynamic import loại bỏ trục locale. Phân phạm vi (scoping) loại bỏ trục trang. Chỉ khi kết hợp cả hai thì dung lượng mới giữ nguyên không đổi.

Đây không phải là đặc tính của thư viện, mà là vấn đề kỷ luật kiến trúc. react-i18next có thể được phân vùng bằng namespace và backend tải lười (lazy backends). use-intl có thể được tách theo từng route. Nhưng không có gì ép buộc điều đó, và một <Button> dùng chung gọi t("common:cta") sẽ âm thầm biến common thành dependency của mọi route. Bản benchmark đo lường điều này dưới dạng "rò rỉ từ các route khác" và "rò rỉ từ các locale khác", và đây là nguyên nhân chính tạo nên sự chênh lệch giữa các thư viện.

Nếu câu trả lời của bạn cho câu hỏi 3 là "nhiều locale, nhiều trang", hãy cân nhắc phần này 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 sẽ phân tích sâu hơn về khía cạnh bảo trì của cùng lựa chọn này.

Các ứng cử viên

Kích thước thư viện được lấy từ bài benchmark trên TanStack Start: provider kèm hook trong một component trống, sau khi bundling, tree-shaking và minification, với 10 trang và 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 benchmark và có thể thay đổi theo các bản phát hành. Hãy chạy benchmark 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.

Có hai điều bảng so sánh không thể hiện. Paraglide hầu như không có dung lượng thư viện vì nó sinh mã trực tiếp vào repo của bạn, đồng nghĩa với việc cần thêm bước sinh lại mã trước mỗi lần commit và tiềm ẩn nguy cơ merge conflict trên các file được sinh ra. Còn Intlayer yêu cầu một plugin bundler (vite-intlayer hoặc tương đương), do đó không thể chạy trong môi trường không có bước build (no-build setup).

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

Những điểm hạn chế của từng thư viện

Những hạn chế thực tế, bởi vì lựa chọn nào cũng có điểm trừ.

• react-i18next: thư viện nặng nhất trong danh sách, định dạng số nhiều riêng, type safety cần bạn tự cấu hình và duy trì, các dead key tích tụ âm thầm theo thời gian.
• react-intl: DX dài dòng (useIntl() rồi formatMessage({ id })), instance toàn cục gắn với nhiều node.
• use-intl: dễ bắt đầu nhưng khó tối ưu. Việc kết hợp namespace, dynamic loading và type làm chậm tốc độ phát triển khá nhiều.
• Lingui: cần thêm bước build extract / compile, nhiều cú pháp chồng chéo (t(), tagged template, i18n.t(), <Trans>) gây bối rối cho cả lập trình viên lẫn trợ lý AI.
• Paraglide: sinh các file mã nguồn trực tiếp vào repo, tree-shaking không có tác dụng trong bài benchmark React, và locale được đọc từ bộ lưu trữ trên mỗi node thay vì từ một store.
• Tolgee: không có type cho key, quá trình làm quen ban đầu khó hơn, điểm mạnh lớn nhất là khả năng chỉnh sửa trực tiếp trong ngữ cảnh (in-context editing).
• Intlayer: bắt buộc dùng plugin build, hệ sinh thái nhỏ hơn, hỗ trợ ICU ở mức một phần, nội dung phân tán khắp codebase theo thiết kế nên việc xuất một file JSON duy nhất cho biên dịch viên cần công cụ hỗ trợ.
• gt-react, lingo.dev: không được khuyến nghị trong benchmark: lỗi hạn ngạch (quota) khi build, phụ thuộc nhà cung cấp (vendor lock-in), và các vấn đề phản ứng dữ liệu (reactivity) đòi hỏi phải ép provider re-render.

Mã nguồn thực tế trông như thế nào

Cùng một component, phần tóm tắt giỏ hàng gồm tiêu đề và dạng số nhiều, được viết bằng từng ứng cử viên. Điểm thú vị không nằm ở chính component, mà ở vị trí lưu trữ nội dung và những gì trình kiểm tra kiểu dữ liệu (type checker) nhận biết được về nó.

{
  "title": "Your cart",
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}

import type { FC } from "react";
import { useTranslation } from "react-i18next";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { t } = useTranslation("cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

{
  "cart.title": "Your cart",
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

import type { FC } from "react";
import { FormattedMessage, useIntl } from "react-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const intl = useIntl();

  return (
    <section>
      <h2>
        <FormattedMessage id="cart.title" />
      </h2>
      <p>{intl.formatMessage({ id: "cart.items" }, { count })}</p>
    </section>
  );
};

{
  "Cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

import type { FC } from "react";
import { useTranslations } from "use-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const t = useTranslations("Cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

msgid "Your cart"
msgstr "Votre panier"

msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# article} other {# articles}}"

import type { FC } from "react";
import { Plural, Trans } from "@lingui/react/macro";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>
      <Trans>Your cart</Trans>
    </h2>
    <p>
      <Plural value={count} one="# item" other="# items" />
    </p>
  </section>
);

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

import type { FC } from "react";
import { m } from "../paraglide/messages.js";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>{m.cart_title()}</h2>
    <p>{m.cart_items({ count })}</p>
  </section>
);

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

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      vi: "Giỏ hàng của bạn",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      vi: plural({ one: "{{count}} sản phẩm", other: "{{count}} sản phẩm" }),
      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;

import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { title, items } = useIntlayer("cart-summary");

  return (
    <section>
      <h2>{title}</h2>
      <p>{items(count)}</p>
    </section>
  );
};

Bạn đã đang sử dụng react-i18next, react-intl hoặc Lingui? Các adapter tương thích (react-i18next, react-intl, Lingui) sẽ tạo alias cho các import ở cấp độ bundler, giúp API hiện tại tiếp tục hoạt động trong khi bạn chuyển đổi từng component một. Hướng dẫn chuyển đổi sẽ hướng dẫn các phần còn lại.

Trước khi bạn đưa ra quyết định

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

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

Commits, thời gian phản hồi issue, và liệu bản minor release gần nhất có phải trong năm nay hay không. Một thiết kế tốt nhưng không có người duy trì sẽ sớm trở thành một gánh nặng cần di chuyển mã nguồn sau này.

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

Thư viện có lượt tải nhiều nhất là thư viện ra mắt đầu tiên, chứ không hẳn là thư viện phù hợp nhất cho một codebase React năm 2026. Lượt tải phản ánh lịch sử, không phản ánh mức độ tương thích.

Hãy hỏi ai là người trả tiền cho maintainer, và họ kinh doanh cái gì.

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

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

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

Tính an toàn kiểu dữ liệu (type safety) có sẵn ngay từ đầu.

Không phải kiểu "có thể định kiểu với cấu hình bổ sung", mà là "một key sai sẽ làm fail tsc ngay trên bản cài đặt mới tinh". Hãy kiểm tra điều gì xảy ra với một key không tồn tại, và với 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 ra. Quá trình build của Intlayer sẽ loại bỏ các trường không dùng và ghi log lại (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ị loại bỏ qua tree-shaking. Tất cả các thư viện còn lại đều để việc dọn dẹp cho bạn tự xử lý.

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

Thời gian thiết lập đế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 đến phần khai báo, một CLI để fill, test và push, cùng phương thức cho người không phải lập trình viên 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

Đọc thêm

• Benchmark các thư viện i18n: kích thước bundle, rò rỉ và thời gian chuyển đổi locale và báo cáo TanStack Start
• React i18n: mô hình provider hoạt động như thế nào và chi phí ra sao
• react-i18next so với react-intl so với Intlayer, so sánh từng tính năng
• next-i18next so với next-intl so với Intlayer
• Lịch sử của JavaScript i18n
• Trình biên dịch so với i18n khai báo
• i18n theo từng component so với tập trung
• Cách tối ưu hóa bundle hoạt động trong thời gian build
• Thiết lập i18n trong ứng dụng Vite + React
• Hướng dẫn tương tự cho Vue, Svelte và Solid