Auteur:
    Création:2026-06-12Dernière mise à jour:2026-06-26

    Variantes

    Une variante est un ensemble de fichiers de contenu qui partagent la même clé de dictionnaire (key) mais portent chacun une valeur variant différente. Intlayer sert le fichier approprié en fonction du sélecteur passé à useIntlayer.

    La valeur variant peut prendre deux formes :

    • Une chaîne — une seule alternative nommée (tests A/B, bannières saisonnières, feature flags).
    • Un objet — un discriminant structuré adressé par un ensemble de champs (enregistrements de CMS, contenu propre à un utilisateur, tout contenu indexé par un identifiant opaque). L'objet entier constitue l'identité : le sélecteur doit fournir un objet égal pour résoudre l'entrée.
    La forme objet remplace l'ancien champ meta. Partout où vous écriviez meta: { id, … }, écrivez variant: { id, … }, et sélectionnez-la avec { variant: { id, … } }.

    Variantes nommées (chaîne)

    Chaque fichier représente une alternative nommée. Omettre variant (ou le définir sur "default") le marque comme valeur par défaut (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;

    Consommer des variantes nommées

    Variante par défaut

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

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

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

    Variante nommée

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

    Variante nommée avec locale explicite

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

    Variantes objet (structurées)

    Une variante objet adresse le contenu par un ensemble arbitraire de paires clé-valeur déclarées dans le champ variant — permettant de modéliser des enregistrements de CMS, du contenu propre à un utilisateur ou tout contenu dont la clé est un identifiant opaque. L'objet entier constitue l'identité : le sélecteur doit fournir un objet égal pour que l'entrée soit résolue.

    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;

    Consommer des variantes objet

    Passez l'objet correspondant à variant. Chaque champ déclaré sur le dictionnaire doit être fourni et égal ; sinon le résultat est null. L'ordre des champs n'a pas d'importance.

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

    Avec une locale explicite

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

    Champ manquant — aucune correspondance

    ts
    // Renvoie null : `userId` est manquant, donc l'objet ne correspond pas à la variante déclaréeconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Mode de chargement

    Les variantes objet sont souvent chargées de façon différée. Définissez importMode sur le dictionnaire pour contrôler ce comportement :

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

export default dictionary;

    Voir optimisation du bundle pour les détails sur les modes static, dynamic et fetch.

    Cas d'usage typiques

    • Tests A/B de texte pilotés par une clé d'expérience
    • Bannières saisonnières ou promotionnelles
    • Messages sous feature flag
    • Campagnes marketing spécifiques à une locale
    • Texte marketing par produit géré dans un CMS
    • Contenu propre à un utilisateur ou à un compte
    • Tout contenu indexé par un identifiant opaque à l'exécution
    Collections
    Fichier par locale