Penulis:
    Dibuat:2026-06-12Terakhir diperbarui:2026-08-04

    Varian

    Sebuah varian adalah sekumpulan file konten yang berbagi key kamus yang sama tetapi masing-masing membawa nilai variant yang berbeda. Intlayer menyajikan file yang sesuai berdasarkan selektor yang diberikan ke useIntlayer.

    Nilai variant dapat berupa dua bentuk:

    • String — satu alternatif bernama (pengujian A/B, banner musiman, feature flag).
    • Objek — diskriminator terstruktur yang dialamatkan oleh sekumpulan field (record CMS, konten khusus pengguna, konten apa pun yang dikunci oleh ID buram). Seluruh objek adalah identitasnya: selektor harus memberikan objek yang sama untuk menyelesaikan entri.
    Bentuk objek menggantikan field meta sebelumnya. Di mana pun Anda dulu menulis meta: { id, … }, tulis variant: { id, … }, dan pilih dengan { variant: { id, … } }.

    Varian bernama (string)

    Setiap file mewakili satu alternatif bernama. Menghilangkan variant (atau mengaturnya ke "default") menandainya sebagai fallback.

    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;

    Varian parsial

    Varian hanya mendeklarasikan kunci yang ditimpanya; sisanya diwarisi dari entri default.

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

const dictionary = {
  key: "hero-banner",
  variant: "summer",
  content: {
    headline: t({
      en: "Build faster all summer",
      fr: "Développez plus vite tout l'été",
    }),
  },
} satisfies Dictionary;

export default dictionary;
    tsx
    useIntlayer("hero-banner", { variant: "summer" });// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — `cta` diwarisiuseIntlayer("hero-banner", { variant: "never-declared" });// → entri default

    Jadi Anda hanya menambahkan file varian di mana kata-katanya benar-benar berbeda. Sebuah kunci hanya menjadi null jika mendeklarasikan varian tetapi tidak ada entri default.

    Mengonsumsi varian bernama

    Varian default

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

export const Hero = () => {
  const { headline, cta } = useIntlayer("hero-banner");
  // → varian default

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

    Varian bernama

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

    Varian bernama dengan locale eksplisit

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

    Varian objek (terstruktur)

    Varian objek mengalamatkan konten dengan sekumpulan pasangan key-value sewenang-wenang yang dideklarasikan di field variant — memungkinkan pemodelan record CMS, konten khusus pengguna, atau konten apa pun yang kuncinya berupa ID buram. Seluruh objek adalah identitasnya: selektor harus memberikan objek yang sama agar entri diselesaikan.

    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;

    Mengonsumsi varian objek

    Berikan objek yang cocok ke variant. Setiap field yang dideklarasikan pada kamus harus disediakan dan sama; jika tidak, hasilnya null. Urutan field tidak penting.

    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>;
};

    Dengan locale eksplisit

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

    Field hilang — tidak cocok

    ts
    // Mengembalikan null: `userId` hilang, sehingga objek tidak cocok dengan varian yang dideklarasikanconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Varian ambien

    Beberapa dimensi varian tetap sepanjang satu sesi — tenant, jenis sekolah, tingkat paket. Semuanya diselesaikan sekali, dan tidak ada komponen yang perlu meneruskannya secara manual.

    Jangan membungkus useIntlayer dalam hook Anda sendiri untuk menyuntikkannya. Optimasi saat build hanya menulis ulang pemanggilan literal useIntlayer("key") yang diimpor dari paket framework, sehingga apa pun di balik pembungkus tidak akan ikut dibundel.

    Sebagai gantinya, deklarasikan varian sekali pada provider, persis seperti locale:

    App.tsx
    import { IntlayerProvider } from "react-intlayer";

export const App = ({ locale, schoolType }) => (
  <IntlayerProvider locale={locale} variant={schoolType}>
    <Hero />
  </IntlayerProvider>
);

    Setiap pembacaan kamus di bawah provider kini diselesaikan terhadap varian tersebut, dan selektor di titik pemanggilan selalu menang:

    tsx
    useIntlayer("hero-banner");// → varian dari provideruseIntlayer("hero-banner", { variant: "summer" });// → "summer" — menggantikan varian provider, bukan memperluasnya

    Bentuk

    Prop variant menerima tiga bentuk:

    Bentuk Arti
    variant="school1" satu varian bernama untuk setiap kunci
    variant={["school1", "default"]} rantai preferensi terurut
    variant={{ "hero-banner": "school1", default: "base" }} satu varian per kunci kamus

    Rantai preferensi

    Rantai dicoba dari kiri ke kanan terhadap entri yang dideklarasikan setiap kunci, dan yang pertama dideklarasikan menang. Bila tidak ada yang dideklarasikan, entri default implisit digunakan — persis seperti untuk nilai tunggal.

    tsx
    <IntlayerProvider variant={["school1", "school2"]} />// `hero-banner` tidak mendeklarasikan entri `school1` tetapi mendeklarasikan `school2` → "school2"// kunci yang tidak mendeklarasikan keduanya → entri default

    Jadi ["black_friday", "summer"] dibaca sebagai «black friday jika kunci ini memilikinya, jika tidak summer, jika tidak default». Rantai juga diterima di titik pemanggilan:

    tsx
    useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
    Perhatikan bahwa ini adalah kebalikan dari array yang diterima oleh field variant pada berkas konten: di sana array mendeklarasikan satu entri per elemen, di sini ia mengonsumsi entri tersebut sesuai urutan prioritas.

    Peta per kunci

    Alamatkan setiap kunci kamus secara terpisah. Entri default yang dicadangkan mencakup semua kunci yang tidak terdaftar:

    tsx
    <IntlayerProvider  variant={{    "hero-banner": "school1",    product: ["school1", "default"],    default: "base",  }}/>
    Pada provider, objek biasa selalu dibaca sebagai peta per kunci, bukan sebagai varian objek — keduanya identik secara struktural. Untuk menetapkan varian objek secara global, sarangkan di bawah sebuah entri: variant={{ default: { id: "prod_abc" } }}.

    Karena kunci pada peta diperiksa terhadap kunci kamus yang Anda deklarasikan, salah ketik — atau varian objek yang ditulis langsung, seperti variant={{ id: "prod_abc" }} — adalah galat saat kompilasi.

    Mode pemuatan

    Varian objek sering dimuat secara malas. Atur importMode pada kamus untuk mengendalikannya:

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

export default dictionary;

    Lihat optimasi bundle untuk detail tentang mode static, dynamic, dan fetch.

    Kasus penggunaan umum

    • Pengujian A/B teks yang digerakkan oleh kunci eksperimen
    • Banner musiman atau promosi
    • Pesan ber-feature flag
    • Kampanye pemasaran spesifik locale
    • Teks pemasaran per-produk yang dikelola di CMS
    • Konten khusus pengguna atau akun
    • Konten apa pun yang dikunci oleh ID buram saat runtime
    Koleksi
    File untuk setiap lokal