Autor:
    Criação:2026-06-12Última atualização:2026-06-26

    Variantes

    Uma variante é um conjunto de arquivos de conteúdo que compartilham a mesma chave de dicionário (key), mas cada um carrega um valor variant diferente. O Intlayer serve o arquivo apropriado com base no seletor passado para useIntlayer.

    O valor de variant pode assumir duas formas:

    • Uma string — uma única alternativa nomeada (testes A/B, banners sazonais, feature flags).
    • Um objeto — um discriminador estruturado endereçado por um conjunto de campos (registros de CMS, conteúdo específico do usuário, qualquer conteúdo cuja chave é um ID opaco). O objeto inteiro é a identidade: o seletor deve fornecer um objeto igual para resolver a entrada.
    A forma de objeto substitui o antigo campo meta. Onde você antes escrevia meta: { id, … }, escreva variant: { id, … } e selecione-a com { variant: { id, … } }.

    Variantes nomeadas (string)

    Cada arquivo representa uma alternativa nomeada. Omitir variant (ou defini-lo como "default") o marca como 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;

    Consumir variantes nomeadas

    Variante padrão

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

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

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

    Variante nomeada

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

    Variante nomeada com locale explícito

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

    Variantes de objeto (estruturadas)

    Uma variante de objeto endereça o conteúdo por um conjunto arbitrário de pares chave-valor declarados no campo variant — possibilitando modelar registros de CMS, conteúdo específico do usuário ou qualquer conteúdo cuja chave seja um ID opaco. O objeto inteiro é a identidade: o seletor deve fornecer um objeto igual para que a entrada seja resolvida.

    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

    Passe o objeto correspondente para variant. Cada campo declarado no dicionário deve ser fornecido e igual; caso contrário, o resultado é null. A ordem dos campos não 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>;
};

    Com locale explícito

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

    Campo ausente — sem correspondência

    ts
    // Retorna null: `userId` está ausente, então o objeto não corresponde à variante declaradaconst content = useIntlayer("product", { variant: { id: "prod_abc" } });

    Modo de carregamento

    As variantes de objeto costumam ser carregadas de forma preguiçosa. Defina importMode no dicionário para controlar isso:

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

export default dictionary;

    Veja otimização do bundle para detalhes sobre os modos static, dynamic e fetch.

    Casos de uso típicos

    • Testes A/B de texto orientados por uma chave de experimento
    • Banners sazonais ou promocionais
    • Mensagens com feature flag
    • Campanhas de marketing específicas por locale
    • Texto de marketing por produto gerenciado em um CMS
    • Conteúdo específico do usuário ou da conta
    • Qualquer conteúdo indexado por um ID opaco em tempo de execução
    Coleções
    Arquivo por locale