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

    Biến thể

    Một biến thể là một tập hợp các tệp nội dung dùng chung key từ điển nhưng mỗi tệp mang một giá trị variant khác nhau. Intlayer phục vụ tệp phù hợp dựa trên bộ chọn được truyền cho useIntlayer.

    Giá trị variant có thể có hai dạng:

    • Một chuỗi — một lựa chọn được đặt tên duy nhất (thử nghiệm A/B, banner theo mùa, feature flag).
    • Một đối tượng — một bộ phân biệt có cấu trúc được định địa chỉ bằng một tập hợp trường (bản ghi CMS, nội dung riêng theo người dùng, bất kỳ nội dung nào được khóa bằng một ID mờ). Toàn bộ đối tượng chính là danh tính: bộ chọn phải cung cấp một đối tượng bằng nhau để phân giải mục.
    Dạng đối tượng thay thế trường meta trước đây. Ở bất cứ đâu trước kia bạn viết meta: { id, … }, hãy viết variant: { id, … }, và chọn nó bằng { variant: { id, … } }.

    Biến thể được đặt tên (chuỗi)

    Mỗi tệp đại diện cho một lựa chọn được đặt tên. Bỏ qua variant (hoặc đặt thành "default") đánh dấu nó là dự phòng.

    hero-banner.content.ts
    import { t, type Dictionary } from "intlayer";

const dictionary = {
  key: "hero-banner",
  variant: "default",
  content: {
    headline: t({
      en: "Build faster with Intlayer",
      fr: "Développez plus vite avec Intlayer",
    }),
    cta: t({ en: "Get started", fr: "Commencer" }),
  },
} satisfies Dictionary;

export default dictionary;
    hero-banner.black-friday.content.ts
    import { t, type Dictionary } from "intlayer";

const dictionary = {
  key: "hero-banner",
  variant: "black_friday",
  content: {
    headline: t({
      en: "50 % off — today only",
      fr: "−50 % — aujourd'hui seulement",
    }),
    cta: t({ en: "Shop now", fr: "Acheter maintenant" }),
  },
} satisfies Dictionary;

export default dictionary;

    Sử dụng biến thể được đặt tên

    Biến thể mặc định

    Hero.tsx
    import { useIntlayer } from "react-intlayer";

export const Hero = () => {
  const { headline, cta } = useIntlayer("hero-banner");
  // → biến thể mặc định

  return (
    <section>
      <h1>{headline}</h1>
      <a>{cta}</a>
    </section>
  );
};

    Biến thể được đặt tên

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

    Biến thể được đặt tên với locale tường minh

    tsx
    const content = useIntlayer("hero-banner", {  variant: "black_friday",  locale: "fr",});

    Biến thể đối tượng (có cấu trúc)

    Một biến thể đối tượng định địa chỉ nội dung bằng một tập hợp cặp khóa-giá trị tùy ý được khai báo trong trường variant — giúp mô hình hóa bản ghi CMS, nội dung riêng theo người dùng, hoặc bất kỳ nội dung nào có khóa là một ID mờ. Toàn bộ đối tượng chính là danh tính: bộ chọn phải cung cấp một đối tượng bằng nhau để mục được phân giải.

    product.abc.content.ts
    import { t, type Dictionary } from "intlayer";

const dictionary = {
  key: "product",
  variant: { id: "prod_abc", userId: "user_123" },
  content: {
    name: t({ en: "Widget Pro", fr: "Widget Pro" }),
    description: t({ en: "The best widget.", fr: "Le meilleur widget." }),
  },
} satisfies Dictionary;

export default dictionary;
    product.abcd.content.ts
    import { t, type Dictionary } from "intlayer";

const dictionary = {
  key: "product",
  variant: { id: "prod_abcd", userId: "user_123" },
  content: {
    name: t({ en: "Widget Lite", fr: "Widget Lite" }),
    description: t({ en: "A lighter option.", fr: "Une option plus légère." }),
  },
} satisfies Dictionary;

export default dictionary;

    Sử dụng biến thể đối tượng

    Truyền đối tượng khớp cho variant. Mọi trường được khai báo trên từ điển phải được cung cấp và bằng nhau; nếu không, kết quả là null. Thứ tự các trường không quan trọng.

    Product.tsx
    import { useIntlayer } from "react-intlayer";

export const Product = ({
  productId,
  userId,
}: {
  productId: string;
  userId: string;
}) => {
  const content = useIntlayer("product", {
    variant: { id: productId, userId },
  });

  if (!content) return null;

  return <p>{content.description}</p>;
};

    Với locale tường minh

    tsx
    const content = useIntlayer("product", {  variant: { id: "prod_abc", userId: "user_123" },  locale: "fr",});

    Thiếu trường — không khớp

    ts
    // Trả về null: thiếu `userId`, nên đối tượng không khớp với biến thể đã khai báoconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Chế độ tải

    Biến thể đối tượng thường được tải lười. Đặt importMode trên từ điển để kiểm soát điều này:

    ts
    const dictionary = {
  key: "product",
  importMode: "fetch", // or "dynamic"
  variant: { id: "prod_abc", userId: "user_123" },
  content: { … },
} satisfies Dictionary;

export default dictionary;

    Xem tối ưu hóa bundle để biết chi tiết về các chế độ static, dynamic và fetch.

    Các trường hợp sử dụng điển hình

    • Thử nghiệm A/B nội dung được điều khiển bằng khóa thí nghiệm
    • Banner theo mùa hoặc khuyến mãi
    • Thông điệp gắn feature flag
    • Chiến dịch tiếp thị riêng theo locale
    • Nội dung tiếp thị theo từng sản phẩm được quản lý trong CMS
    • Nội dung riêng theo người dùng hoặc tài khoản
    • Bất kỳ nội dung nào được khóa bằng một ID mờ trong thời gian chạy
    Bộ sưu tập
    File cho mỗi ngôn ngữ