Author:

Creation:2026-06-12Last update:2026-06-26

Reference this doc to your favorite AI assistant

ChatGPT

Claude

DeepSeek

Google AI mode Gemini

Perplexity Mistral

Grok

Ask your question and get a summary of the document by referencing this page and the AI provider of your choice

Version History

"Release of the variants feature"
v9.0.012/06/2026
"`variant` now accepts a string or an object — the former `meta` / dynamic records are declared as object variants"
v9.1.026/06/2026

The content of this page was translated using an AI.

See the last version of the original content in English

Edit this doc

If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.

GitHub link to the documentation

Copy

Copy doc Markdown to clipboard

Variants

Name: Intlayer
Author: Intlayer

A variant is a set of content files that share the same dictionary key but each carry a different variant value. Intlayer serves the appropriate file based on the selector passed to useIntlayer.

The variant value can take two forms:

A string — a single named alternative (A/B tests, seasonal banners, feature flags).
An object — a structured discriminator addressed by a set of fields (CMS records, user-specific copy, any content keyed by an opaque ID). The whole object is the identity: the selector must provide an equal object to resolve the entry.

The object form replaces the former meta field. Anywhere you previously wrote meta: { id, … }, write variant: { id, … }, and select it with { variant: { id, … } }.

Named (string) variants

Each file represents one named alternative. Omitting variant (or setting it to "default") marks it as the fallback.

hero-banner.content.ts

Copy code

Copy the code to the clipboard

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

Copy code

Copy the code to the clipboard

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;

Consuming named variants

Default variant

Hero.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "react-intlayer";

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

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

Hero.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "next-intlayer";

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

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

Hero.vue

Copy code

Copy the code to the clipboard

<script setup>
import { useIntlayer } from "vue-intlayer";
const { headline, cta } = useIntlayer("hero-banner");
</script>

<template>
  <section>
    <h1>{{ headline }}</h1>
    <a>{{ cta }}</a>
  </section>
</template>

Hero.svelte

Copy code

Copy the code to the clipboard

<script lang="ts">
import { useIntlayer } from "svelte-intlayer";
const content = useIntlayer("hero-banner");
</script>

<section>
  <h1>{$content.headline}</h1>
  <a>{$content.cta}</a>
</section>

Hero.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "preact-intlayer";

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

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

Hero.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "solid-intlayer";

export const Hero = () => {
  const content = useIntlayer("hero-banner");
  // → default variant

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

hero.component.ts

Copy code

Copy the code to the clipboard

import { Component } from "@angular/core";
import { useIntlayer } from "angular-intlayer";

@Component({
  selector: "app-hero",
  template: `
    <section>
      <h1>{{ content().headline }}</h1>
      <a>{{ content().cta }}</a>
    </section>
  `,
})
export class HeroComponent {
  content = useIntlayer("hero-banner");
}

hero.js

Copy code

Copy the code to the clipboard

import { useIntlayer } from "vanilla-intlayer";const { headline, cta } = useIntlayer("hero-banner");document.body.innerHTML = `  <section>    <h1>${headline}</h1>    <a>${cta}</a>  </section>`;

import { useIntlayer } from "vanilla-intlayer";const { headline, cta } = useIntlayer("hero-banner");document.body.innerHTML = `  <section>    <h1>${headline}</h1>    <a>${cta}</a>  </section>`;

Named variant

tsx

Copy code

Copy the code to the clipboard

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

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

Named variant with explicit locale

tsx

Copy code

Copy the code to the clipboard

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

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

Object (structured) variants

An object variant addresses content by an arbitrary set of key-value pairs declared in the variant field — making it possible to model CMS records, user-specific copy, or any content whose key is an opaque ID. The whole object is the identity: the selector must provide an equal object for the entry to resolve.

product.abc.content.ts

Copy code

Copy the code to the clipboard

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

Copy code

Copy the code to the clipboard

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;

Consuming object variants

Pass the matching object to variant. Every field declared on the dictionary must be provided and equal; otherwise the result is null. Field order does not matter.

Product.tsx

Copy code

Copy the code to the clipboard

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

Product.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "next-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>;
};

Product.vue

Copy code

Copy the code to the clipboard

<script setup>
import { useIntlayer } from "vue-intlayer";

const props = defineProps({
  productId: String,
  userId: String,
});

const content = useIntlayer("product", {
  variant: { id: props.productId, userId: props.userId },
});
</script>

<template>
  <p v-if="content">{{ content.description }}</p>
</template>

Product.svelte

Copy code

Copy the code to the clipboard

<script lang="ts">
import { useIntlayer } from "svelte-intlayer";

export let productId: string;
export let userId: string;

const content = useIntlayer("product", {
  variant: { id: productId, userId },
});
</script>

{#if $content}
  <p>{$content.description}</p>
{/if}

Product.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "preact-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>;
};

Product.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "solid-intlayer";

export const Product = (props: {
  productId: string;
  userId: string;
}) => {
  const content = useIntlayer("product", {
    variant: { id: props.productId, userId: props.userId },
  });

  return (
    <>
      {content() && <p>{content().description}</p>}
    </>
  );
};

product.component.ts

Copy code

Copy the code to the clipboard

import { Component, Input, OnInit } from "@angular/core";
import { useIntlayer } from "angular-intlayer";

@Component({
  selector: "app-product",
  template: `
    @if (content()) {
      <p>{{ content().description }}</p>
    }
  `,
})
export class ProductComponent implements OnInit {
  @Input() productId!: string;
  @Input() userId!: string;

  content: any;

  ngOnInit() {
    this.content = useIntlayer("product", {
      variant: { id: this.productId, userId: this.userId },
    });
  }
}

product.js

Copy code

Copy the code to the clipboard

import { useIntlayer } from "vanilla-intlayer";const content = useIntlayer("product", {  variant: { id: "prod_abcd", userId: "user_123" },});if (content) {  document.body.innerHTML = `<p>${content.description}</p>`;}

import { useIntlayer } from "vanilla-intlayer";const content = useIntlayer("product", {  variant: { id: "prod_abcd", userId: "user_123" },});if (content) {  document.body.innerHTML = `<p>${content.description}</p>`;}

With explicit locale

tsx

Copy code

Copy the code to the clipboard

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

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

Missing field — no match

Copy code

Copy the code to the clipboard

// Returns null: `userId` is missing, so the object does not match the declared variantconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

// Returns null: `userId` is missing, so the object does not match the declared variantconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

Loading mode

Object variants are often loaded lazily. Set importMode on the dictionary to control this:

Copy code

Copy the code to the clipboard

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

export default dictionary;

See bundle optimization for details on static, dynamic, and fetch modes.

Typical use-cases

A/B copy tests driven by an experiment key
Seasonal or promotional banners
Feature-flagged messaging
Locale-specific marketing campaigns
Per-product marketing copy managed in a CMS
User-specific or account-specific content
Any content keyed by an opaque runtime ID

Collections

Per Locale File