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.06/12/2026
"`variant` now accepts a string or an object — the former `meta` / dynamic records are declared as object variants"
v9.1.06/26/2026

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