Autore:
    Creazione:2026-06-12Ultimo aggiornamento:2026-06-26

    Varianti

    Una variante è un insieme di file di contenuto che condividono la stessa chiave del dizionario (key) ma portano ciascuno un valore variant diverso. Intlayer serve il file appropriato in base al selettore passato a useIntlayer.

    Il valore di variant può assumere due forme:

    • Una stringa — una singola alternativa con nome (test A/B, banner stagionali, feature flag).
    • Un oggetto — un discriminatore strutturato indirizzato da un insieme di campi (record di CMS, contenuti specifici per utente, qualsiasi contenuto con chiave un ID opaco). L'intero oggetto è l'identità: il selettore deve fornire un oggetto uguale per risolvere la voce.
    La forma a oggetto sostituisce il precedente campo meta. Ovunque scrivessi meta: { id, … }, scrivi variant: { id, … } e selezionala con { variant: { id, … } }.

    Varianti con nome (stringa)

    Ogni file rappresenta un'alternativa con nome. Omettere variant (o impostarlo su "default") la contrassegna come 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;

    Consumare varianti con nome

    Variante predefinita

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

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

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

    Variante con nome

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

    Variante con nome con locale esplicito

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

    Varianti oggetto (strutturate)

    Una variante oggetto indirizza il contenuto tramite un insieme arbitrario di coppie chiave-valore dichiarate nel campo variant — rendendo possibile modellare record di CMS, contenuti specifici per utente o qualsiasi contenuto la cui chiave è un ID opaco. L'intero oggetto è l'identità: il selettore deve fornire un oggetto uguale affinché la voce venga risolta.

    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;

    Consumare varianti oggetto

    Passa l'oggetto corrispondente a variant. Ogni campo dichiarato nel dizionario deve essere fornito e uguale; altrimenti il risultato è null. L'ordine dei campi non ha importanza.

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

    Con locale esplicito

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

    Campo mancante — nessuna corrispondenza

    ts
    // Restituisce null: manca `userId`, quindi l'oggetto non corrisponde alla variante dichiarataconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Modalità di caricamento

    Le varianti oggetto sono spesso caricate in modo differito. Imposta importMode sul dizionario per controllarlo:

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

export default dictionary;

    Vedi ottimizzazione del bundle per i dettagli sulle modalità static, dynamic e fetch.

    Casi d'uso tipici

    • Test A/B di testo guidati da una chiave di esperimento
    • Banner stagionali o promozionali
    • Messaggistica con feature flag
    • Campagne di marketing specifiche per locale
    • Testo di marketing per prodotto gestito in un CMS
    • Contenuti specifici per utente o account
    • Qualsiasi contenuto indicizzato da un ID opaco a runtime
    Collezioni
    File per locale