Autor:
    Data utworzenia:2026-06-12Ostatnia aktualizacja:2026-08-04

    Warianty

    Wariant to zestaw plików treści, które dzielą ten sam klucz słownika (key), lecz każdy ma inną wartość variant. Intlayer udostępnia odpowiedni plik na podstawie selektora przekazanego do useIntlayer.

    Wartość variant może przyjmować dwie formy:

    • Ciąg znaków — pojedyncza nazwana alternatywa (testy A/B, banery sezonowe, feature flagi).
    • Obiekt — strukturalny dyskryminator adresowany zestawem pól (rekordy CMS, treść zależna od użytkownika, dowolna treść z nieprzezroczystym ID jako kluczem). Tożsamością jest cały obiekt: selektor musi dostarczyć równy obiekt, aby rozwiązać wpis.
    Forma obiektowa zastępuje dawne pole meta. Wszędzie, gdzie wcześniej pisałeś meta: { id, … }, napisz variant: { id, … } i wybierz ją przez { variant: { id, … } }.

    Warianty nazwane (tekstowe)

    Każdy plik reprezentuje jedną nazwaną alternatywę. Pominięcie variant (lub ustawienie na "default") oznacza go jako domyślny.

    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;

    Warianty częściowe

    Wariant deklaruje tylko klucze, które nadpisuje; reszta jest dziedziczona z wpisu domyślnego.

    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` odziedziczoneuseIntlayer("hero-banner", { variant: "never-declared" });// → wpis domyślny

    Dlatego dodajesz plik wariantu tylko tam, gdzie brzmienie faktycznie się różni. Klucz jest rozwiązywany na null tylko wtedy, gdy deklaruje warianty, ale nie ma domyślnego wpisu.

    Korzystanie z wariantów nazwanych

    Wariant domyślny

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

export const Hero = () => {
  const { headline, cta } = useIntlayer("hero-banner");
  // → wariant domyślny

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

    Wariant nazwany

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

    Wariant nazwany z jawnym locale

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

    Warianty obiektowe (strukturalne)

    Wariant obiektowy adresuje treść dowolnym zestawem par klucz-wartość zadeklarowanych w polu variant — co umożliwia modelowanie rekordów CMS, treści zależnej od użytkownika lub dowolnej treści z nieprzezroczystym ID jako kluczem. Tożsamością jest cały obiekt: selektor musi dostarczyć równy obiekt, aby wpis został rozwiązany.

    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;

    Korzystanie z wariantów obiektowych

    Przekaż pasujący obiekt do variant. Każde pole zadeklarowane w słowniku musi zostać podane i być równe; w przeciwnym razie wynik to null. Kolejność pól nie ma znaczenia.

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

    Z jawnym locale

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

    Brakujące pole — brak dopasowania

    ts
    // Zwraca null: brakuje `userId`, więc obiekt nie pasuje do zadeklarowanego wariantuconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Wariant otaczający

    Niektóre wymiary wariantu są stałe przez całą sesję — najemca, typ szkoły, poziom planu. Są rozstrzygane raz i żaden komponent nie powinien przekazywać ich ręcznie.

    Nie opakowuj useIntlayer we własny hook, aby je wstrzyknąć. Optymalizacja na etapie budowania przepisuje wyłącznie dosłowne wywołanie useIntlayer("key") zaimportowane z pakietu frameworka, więc nic za opakowaniem nie trafi do bundla.

    Zamiast tego zadeklaruj wariant raz na dostawcy, dokładnie jak locale:

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

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

    Każdy odczyt słownika poniżej dostawcy rozstrzyga się teraz względem tego wariantu, a selektor w miejscu wywołania zawsze wygrywa:

    tsx
    useIntlayer("hero-banner");// → wariant dostawcyuseIntlayer("hero-banner", { variant: "summer" });// → "summer" — zastępuje wariant dostawcy, nie rozszerza go

    Formy

    Prop variant przyjmuje trzy formy:

    Forma Znaczenie
    variant="school1" jeden nazwany wariant dla każdego klucza
    variant={["school1", "default"]} uporządkowany łańcuch preferencji
    variant={{ "hero-banner": "school1", default: "base" }} jeden wariant na klucz słownika

    Łańcuch preferencji

    Łańcuch jest przechodzony od lewej do prawej względem wpisów deklarowanych przez każdy klucz i wygrywa pierwszy zadeklarowany. Gdy żaden nie jest zadeklarowany, używany jest niejawny wpis domyślny — dokładnie tak jak dla pojedynczej wartości.

    tsx
    <IntlayerProvider variant={["school1", "school2"]} />// `hero-banner` nie deklaruje wpisu `school1`, ale deklaruje `school2` → "school2"// klucz, który nie deklaruje żadnego z nich → wpis domyślny

    Zatem ["black_friday", "summer"] czyta się jako „black friday, jeśli ten klucz go ma, w przeciwnym razie summer, w przeciwnym razie domyślny”. Łańcuchy są akceptowane także w miejscu wywołania:

    tsx
    useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
    Zauważ, że jest to lustrzane odbicie tablicy przyjmowanej przez pole variant pliku treści: tam tablica deklaruje jeden wpis na element, tutaj konsumuje je w kolejności priorytetu.

    Mapa według klucza

    Adresuj każdy klucz słownika osobno. Zarezerwowany wpis default obejmuje wszystkie klucze niewymienione na liście:

    tsx
    <IntlayerProvider  variant={{    "hero-banner": "school1",    product: ["school1", "default"],    default: "base",  }}/>
    Na dostawcy zwykły obiekt jest zawsze odczytywany jako mapa według klucza, nigdy jako wariant obiektowy — oba są strukturalnie identyczne. Aby ustalić wariant obiektowy globalnie, zagnieźdź go pod wpisem: variant={{ default: { id: "prod_abc" } }}.

    Ponieważ klucze mapy są sprawdzane względem zadeklarowanych kluczy słowników, literówka — lub wariant obiektowy zapisany wprost, taki jak variant={{ id: "prod_abc" }} — jest błędem kompilacji.

    Tryb ładowania

    Warianty obiektowe są często ładowane leniwie. Ustaw importMode w słowniku, aby to kontrolować:

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

export default dictionary;

    Zobacz optymalizację bundla, aby poznać szczegóły trybów static, dynamic i fetch.

    Typowe przypadki użycia

    • Testy A/B tekstu sterowane kluczem eksperymentu
    • Banery sezonowe lub promocyjne
    • Komunikaty z feature flag
    • Kampanie marketingowe specyficzne dla locale
    • Teksty marketingowe per produkt zarządzane w CMS
    • Treść zależna od użytkownika lub konta
    • Dowolna treść adresowana nieprzezroczystym ID w czasie wykonywania
    Kolekcje
    Plik dla każdej lokalizacji