Autor:
    Creación:2026-06-12Última actualización:2026-08-04

    Variantes

    Una variante es un conjunto de archivos de contenido que comparten la misma clave de diccionario (key) pero llevan cada uno un valor variant diferente. Intlayer sirve el archivo adecuado según el selector pasado a useIntlayer.

    El valor de variant puede adoptar dos formas:

    • Una cadena — una única alternativa con nombre (pruebas A/B, banners de temporada, feature flags).
    • Un objeto — un discriminador estructurado direccionado por un conjunto de campos (registros de CMS, contenido específico de usuario, cualquier contenido indexado por un ID opaco). El objeto completo es la identidad: el selector debe proporcionar un objeto igual para resolver la entrada.
    La forma de objeto sustituye al antiguo campo meta. Donde antes escribía meta: { id, … }, escriba variant: { id, … }, y selecciónela con { variant: { id, … } }.

    Variantes con nombre (cadena)

    Cada archivo representa una alternativa con nombre. Omitir variant (o establecerlo en "default") lo marca como el valor de reserva.

    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;

    Variantes parciales

    Una variante declara solo las claves que anula; el resto se hereda de la entrada por defecto.

    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` heredadouseIntlayer("hero-banner", { variant: "never-declared" });// → la entrada por defecto

    Por lo tanto, solo debe agregar un archivo de variante donde la redacción realmente difiera. Una clave se resuelve en null solo cuando declara variantes pero ninguna entrada por defecto.

    Consumir variantes con nombre

    Variante por defecto

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

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

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

    Variante con nombre

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

    Variante con nombre con locale explícito

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

    Variantes de objeto (estructuradas)

    Una variante de objeto direcciona el contenido mediante un conjunto arbitrario de pares clave-valor declarados en el campo variant — lo que permite modelar registros de CMS, contenido específico de usuario o cualquier contenido cuya clave sea un ID opaco. El objeto completo es la identidad: el selector debe proporcionar un objeto igual para que la entrada se resuelva.

    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;

    Consumir variantes de objeto

    Pase el objeto coincidente a variant. Cada campo declarado en el diccionario debe proporcionarse e ser igual; de lo contrario el resultado es null. El orden de los campos no importa.

    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 explícito

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

    Campo faltante — sin coincidencia

    ts
    // Devuelve null: falta `userId`, por lo que el objeto no coincide con la variante declaradaconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Variante ambiental

    Algunas dimensiones de variante son fijas durante toda una sesión: el inquilino, el tipo de centro, el nivel de plan. Se resuelven una sola vez, y ningún componente debería tener que pasarlas a mano.

    No envuelvas useIntlayer en tu propio hook para inyectarlas. La optimización en tiempo de compilación solo reescribe una llamada literal useIntlayer("key") importada del paquete del framework, por lo que nada detrás de un wrapper se incluye en el bundle.

    En su lugar, declara la variante una sola vez en el proveedor, exactamente igual que locale:

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

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

    Cada lectura de diccionario bajo el proveedor se resuelve ahora con esa variante, y un selector en el punto de llamada siempre gana:

    tsx
    useIntlayer("hero-banner");// → la variante del proveedoruseIntlayer("hero-banner", { variant: "summer" });// → "summer" — sustituye la variante del proveedor, no la extiende

    Formas

    La prop variant acepta tres formas:

    Forma Significado
    variant="school1" una variante nombrada para todas las claves
    variant={["school1", "default"]} una cadena de preferencia ordenada
    variant={{ "hero-banner": "school1", default: "base" }} una variante por clave de diccionario

    Cadena de preferencia

    Una cadena se recorre de izquierda a derecha frente a las entradas que declara cada clave, y gana la primera declarada. Cuando no hay ninguna declarada, se usa la entrada por defecto implícita, exactamente igual que con un valor único.

    tsx
    <IntlayerProvider variant={["school1", "school2"]} />// `hero-banner` no declara una entrada `school1` pero sí declara `school2` → "school2"// una clave que no declara ninguna de las dos → la entrada por defecto

    Así, ["black_friday", "summer"] se lee como «black friday si esta clave la tiene, si no summer, si no por defecto». Las cadenas también se aceptan en el punto de llamada:

    tsx
    useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
    Ten en cuenta que esto es la imagen especular del array aceptado por el campo variant de un archivo de contenido: allí un array declara una entrada por elemento; aquí las consume por orden de prioridad.

    Mapa por clave

    Dirígete a cada clave de diccionario por separado. La entrada reservada default cubre todas las claves no listadas:

    tsx
    <IntlayerProvider  variant={{    "hero-banner": "school1",    product: ["school1", "default"],    default: "base",  }}/>
    En un proveedor, un objeto simple se lee siempre como el mapa por clave, nunca como una variante de objeto: ambos son estructuralmente idénticos. Para fijar una variante de objeto globalmente, anídala bajo una entrada: variant={{ default: { id: "prod_abc" } }}.

    Como las claves del mapa se comprueban contra tus claves de diccionario declaradas, una errata —o una variante de objeto escrita directamente, como variant={{ id: "prod_abc" }}— es un error de compilación.

    Modo de carga

    Las variantes de objeto suelen cargarse de forma diferida. Establezca importMode en el diccionario para controlarlo:

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

export default dictionary;

    Consulte optimización del bundle para detalles sobre los modos static, dynamic y fetch.

    Casos de uso típicos

    • Pruebas A/B de texto dirigidas por una clave de experimento
    • Banners de temporada o promocionales
    • Mensajería con feature flag
    • Campañas de marketing específicas por locale
    • Copia de marketing por producto gestionada en un CMS
    • Contenido específico de usuario o de cuenta
    • Cualquier contenido indexado por un ID opaco en tiempo de ejecución
    Colecciones
    Archivo por locale