Tác giả:
    Ngày tạo:2026-06-14Cập nhật lần cuối:2026-06-29

    Intlayer v9 Mới - Có gì mới?

    Chào mừng bạn đến với Intlayer v9! Bản phát hành lớn này đánh dấu một cột mốc quan trọng trong việc đơn giản hóa lộ trình migration sang Intlayer với các Compat Adapter Packages dành cho các thư viện i18n phổ biến (react-i18next, next-intl, vue-i18n, v.v.) và bổ sung hỗ trợ cho các cấu trúc nội dung phong phú: Collections và Variants.

    Mục lục

    Compat Adapter Packages

    Việc migration sang Intlayer từ các thư viện i18n phổ biến giờ đây dễ dàng hơn bao giờ hết. Chúng tôi đã tạo ra năm compat package cung cấp chính xác các public API tương tự như các thư viện i18n tiêu chuẩn nhưng ủy quyền toàn bộ việc xử lý translation cho Intlayer tại runtime.

    Cung cấp cùng một Public API với Strict Typing

    Bằng cách thay thế các import, bạn sẽ nhận được tất cả các lợi ích của Intlayer (bao gồm cả compile-time type safety dựa trên các dictionary thực tế của bạn) với những thay đổi code tối thiểu:

    • @intlayer/i18next
    • @intlayer/react-i18next
    • @intlayer/next-intl
    • @intlayer/react-intl
    • @intlayer/next-i18next
    • @intlayer/vue-i18n
    • @intlayer/lingui

    Ví dụ, chỉ cần thay đổi:

    ts
    import { useTranslation } from "react-i18next";

    thành:

    ts
    import { useTranslation } from "@intlayer/react-i18next";

    Các key của bạn giờ đây sẽ được strictly typed dựa trên các Intlayer dictionary của bạn, mang lại khả năng auto-completion dot-path đầy đủ trong IDE của bạn!

    Bundler Alias Plugins (Vite, Next.js, Turbopack)

    Để cho phép migration mà không cần phải viết lại tất cả các câu lệnh import một cách thủ công, mỗi compat adapter package đều đi kèm một custom bundler plugin (Vite hoặc Next.js) dưới subpath /plugin.

    Các plugin này tự động rewrite các import hiện có (ví dụ: react-i18next hoặc next-intl) thành các package tương đương @intlayer/* tại build time.

    Ví dụ Next.js (Webpack / Turbopack)

    Thay vì withIntlayer, hãy bọc cấu hình Next.js của bạn bằng compat plugin:

    next.config.ts
    import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

    Ví dụ Vite (React, Vue, Solid, Svelte)

    vite.config.ts
    import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

    Mutualized Runtime Resolver

    Tất cả các compat adapter giờ đây đều định tuyến việc xử lý translation thông qua một runtime parser duy nhất và được tối ưu hóa cao: @intlayer/core/messageFormat.

    • Interpolate Message: Xử lý các cú pháp tiêu chuẩn {{var}} (whitespace & dot-paths), các đối số định dạng ICU ({v, number, percent} v.v.), và các template {var} cơ bản.
    • Message Node Resolver: Xử lý các node lồng nhau: insert(), plural() (quy tắc số nhiều CLDR), enu() (enumeration), gender(), các thẻ HTML, array, và các callable function node.
    • Tokenized Tag Parser: Hỗ trợ các thẻ XML/HTML inline và các thẻ được đánh số (ví dụ: <1>children</1>) để hỗ trợ render rich-text một cách dễ dàng.

    Chi tiết tính năng: Collections & Variants

    Intlayer v9 mở rộng vượt ra ngoài các đối tượng key-value tĩnh, cho phép các dictionary khai báo các cấu trúc layout động được định kiểu đầy đủ (fully typed) từ đầu đến cuối.

    1. Collections

    Định nghĩa một danh sách các item có thứ tự do CMS quản lý (ví dụ: FAQ, sản phẩm, hoặc danh sách blog):

    faq.1.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;
    faq.2.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

    Cách sử dụng:

    ts
    // Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

    2. Variants

    Cung cấp các bản thử nghiệm A/B, seasonal header, feature flag, hoặc các landing page tùy chỉnh:

    Các biến thể chuỗi (ví dụ: thử nghiệm A/B)

    hero.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ vi: "Chào mừng", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      vi: "Mua ngay",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

    Cách sử dụng:

    ts
    const banner = useIntlayer("hero-banner", { variant: "black_friday" });

    Các biến thể đối tượng (ví dụ: Dynamic Records)

    product.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ vi: "Clean Code", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

    Cách sử dụng:

    ts
    // Chỉ tải động item được yêu cầu (yêu cầu Suspense)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

    Vite Plugin: Bundled Compiler & Proxy

    Plugin Vite intlayer() hiện đóng gói compiler và locale-routing proxy trực tiếp, vì vậy hầu hết các dự án chỉ cần một plugin duy nhất trong vite.config.ts:

    vite.config.ts
    import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});
    • Compiler: Kích hoạt tự động khi compiler.enabled được đặt thành true và một đường dẫn compiler.output được cấu hình. Bạn không còn cần phải đăng ký intlayerCompiler() riêng biệt.
    • Proxy: Kích hoạt tự động dựa trên tùy chọn routing.enableProxy mới (true theo mặc định). Nó kết nối middleware phát hiện ngôn ngữ / chuyển hướng / ghi đè trong phát triển, xem trước và SSR sản xuất. Bạn không còn cần phải đăng ký intlayerProxy() riêng biệt.

    Tùy chọn routing.enableProxy

    Một tùy chọn routing.enableProxy mới kiểm soát xem proxy định tuyến locale có được cắm vào hay không. Nó mặc định là true. Vô hiệu hóa nó khi bạn muốn xử lý định tuyến locale của riêng mình:

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Mặc định: true  },};export default config;

    Các plugin độc lập intlayerCompiler() và intlayerProxy() vẫn được xuất cho các cài đặt nâng cao. Đăng ký chúng cùng với intlayer() là an toàn — mỗi plugin loại bỏ chính nó và chỉ chạy một lần.

    Compiler bị tắt theo mặc định

    Kể từ Intlayer v9, compiler bị tắt theo mặc định (compiler.enabled hiện mặc định là false). Để bật trích xuất các file .content.ts của bạn tại thời điểm build, hãy đặt compiler.enabled: true trong cấu hình của bạn:

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Mặc định: false — bắt buộc để bật compiler kể từ v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

    Khi compiler bị tắt, Intlayer bỏ qua bước trích xuất tại thời điểm build và dựa vào các dictionary mà bạn đã khai báo. Chỉ bật nó khi bạn muốn plugin bundler (@intlayer/swc, @intlayer/babel, hoặc plugin Vite intlayer()) tự động trích xuất nội dung.

    React Native: import từ một package duy nhất

    Trong ứng dụng React Native hoặc Expo, bạn không còn cần phải xoay sở giữa react-intlayer và react-native-intlayer nữa. Package react-native-intlayer hiện xuất lại toàn bộ API của react-intlayer (các hook, tiện ích và các đường dẫn phụ /format, /html, và /markdown), và IntlayerProvider của nó tự động áp dụng các polyfill của React Native.

    Import mọi thứ từ package react-native-intlayer duy nhất:

    tsx
    import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";
    bash
    npm install intlayer react-native-intlayer
    Việc import từ react-intlayer vẫn tiếp tục hoạt động, nhưng react-native-intlayer hiện là điểm vào duy nhất được khuyên dùng cho React Native — provider của nó cung cấp các polyfill mà provider định hướng web react-intlayer không có.

    CMS SDK: dùng Intlayer như một cơ sở dữ liệu nội dung headless

    Intlayer v9 cung cấp một SDK gọn gàng, tự xác thực trong @intlayer/api để tương tác với CMS theo chương trình — lấy dự án, lấy từ điển, cũng như đẩy hoặc cập nhật chúng từ máy chủ, script hoặc CI của bạn. Việc xác thực (OAuth2 client_credentials) được xử lý và làm mới tự động cho bạn.

    SDK được tách thành hai import riêng biệt để bundle của bạn chỉ bao gồm những domain bạn thực sự dùng:

    1. createIntlayerCMS — một bộ xác thực nhẹ giữ thông tin đăng nhập và token được quản lý (không đóng gói client domain nào).
    2. dictionaryEndpoint, projectEndpoint, … — các bộ liên kết endpoint theo từng domain, mỗi cái được import từ subpath riêng.
    cms.ts
    import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// Cấu hình là tùy chọn: thông tin đăng nhập sẽ dùng INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET được phân giải bởi `@intlayer/config/built`.const cms = createIntlayerCMS();// Đọcconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Ghi — dùng CMS như một cơ sở dữ liệuawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
    Bảo mật: thông tin đăng nhập CMS cấp quyền ghi vào nội dung của bạn. Luôn chỉ tạo bộ xác thực ở phía máy chủ — không bao giờ gửi clientId / clientSecret xuống trình duyệt.

    Lưu ý khi migration từ v8

    Nếu bạn đang nâng cấp từ v8, lưu ý rằng v9 không bao gồm các breaking change. Tuy nhiên, dưới đây là các thay đổi chính:

    • Compiler bị tắt theo mặc định: compiler.enabled hiện mặc định là false. Nếu bạn dựa vào việc trích xuất các file .content.ts tại thời điểm build, hãy đặt compiler.enabled: true trong intlayer.config.ts của bạn.
    • Locales & Dialects: Nếu sử dụng các dependency i18n bên ngoài, hãy thêm các compat adapter plugin tương ứng của chúng vào cấu hình hoặc thiết lập bundler của bạn để tự động rewrite các import.
    • Custom Selectors: Khi gọi useIntlayer, tham số thứ hai giờ đây được dành riêng cho một đối tượng option chứa { locale, item, variant }. Nếu trước đây bạn đã truyền trực tiếp một chuỗi locale, bạn vẫn có thể làm như vậy, nhưng việc sử dụng đối tượng options được khuyến nghị cho các lựa chọn nâng cao.

    Liên kết hữu ích

    Language Server Protocol
    v8