Varianten

Eine Variante ist eine Gruppe von Inhaltsdateien, die denselben Wörterbuch-key teilen, aber jeweils einen anderen variant-Wert tragen. Intlayer liefert die passende Datei basierend auf dem an useIntlayer übergebenen Selektor.

Der variant-Wert kann zwei Formen annehmen:

• Ein String — eine einzelne benannte Alternative (A/B-Tests, saisonale Banner, Feature-Flags).
• Ein Objekt — ein strukturierter Diskriminator, der über eine Reihe von Feldern adressiert wird (CMS-Datensätze, benutzerspezifische Inhalte, beliebige Inhalte mit einer opaken ID als Schlüssel). Das gesamte Objekt ist die Identität: Der Selektor muss ein gleiches Objekt liefern, um den Eintrag aufzulösen.

Die Objektform ersetzt das frühere meta-Feld. Überall, wo Sie zuvor meta: { id, … } geschrieben haben, schreiben Sie variant: { id, … } und wählen es mit { variant: { id, … } } aus.

Benannte (String-)Varianten

Jede Datei stellt eine benannte Alternative dar. Das Weglassen von variant (oder das Setzen auf "default") markiert sie als Fallback.

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;

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;

Teilvarianten

Eine Variante deklariert nur die Schlüssel, die sie überschreibt; der Rest wird vom Standardeintrag geerbt.

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;

useIntlayer("hero-banner", { variant: "summer" });
// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — `cta` geerbt

useIntlayer("hero-banner", { variant: "never-declared" });
// → der Standardeintrag

Fügen Sie also nur dort eine Varianten-Datei hinzu, wo der Wortlaut tatsächlich abweicht. Ein Schlüssel wird nur dann in null aufgelöst, wenn er Varianten deklariert, aber keinen Standardeintrag.

Benannte Varianten verwenden

Standardvariante

import { useIntlayer } from "react-intlayer";

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

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

import { useIntlayer } from "next-intlayer";

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

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

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

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

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

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

import { useIntlayer } from "preact-intlayer";

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

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

import { useIntlayer } from "solid-intlayer";

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

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

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

import { useIntlayer } from "vanilla-intlayer";

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

document.body.innerHTML = `
<section>
  <h1>${headline}</h1>
  <a>${cta}</a>
</section>
`;

Benannte Variante

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

Benannte Variante mit explizitem Locale

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

Objekt-Varianten (strukturiert)

Eine Objekt-Variante adressiert Inhalte über eine beliebige Menge von Schlüssel-Wert-Paaren, die im variant-Feld deklariert sind — wodurch sich CMS-Datensätze, benutzerspezifische Inhalte oder beliebige Inhalte mit einer opaken ID als Schlüssel modellieren lassen. Das gesamte Objekt ist die Identität: Der Selektor muss ein gleiches Objekt liefern, damit der Eintrag aufgelöst wird.

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;

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;

Objekt-Varianten verwenden

Übergeben Sie das passende Objekt an variant. Jedes im Wörterbuch deklarierte Feld muss angegeben und gleich sein; andernfalls ist das Ergebnis null. Die Reihenfolge der Felder spielt keine Rolle.

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

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

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

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

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

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

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

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

Mit explizitem Locale

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

Fehlendes Feld — keine Übereinstimmung

// Gibt null zurück: `userId` fehlt, daher passt das Objekt nicht zur deklarierten Variante
const content = useIntlayer("product", { variant: { id: "prod_abc" } });

Ambiente Variante

Manche Variantendimensionen stehen für eine ganze Sitzung fest — der Mandant, der Schultyp, die Tarifstufe. Sie werden einmal aufgelöst, und keine Komponente sollte sie von Hand durchreichen müssen.

Kapseln Sie useIntlayer nicht in einen eigenen Hook, um sie einzuschleusen. Die Optimierung zur Bauzeit schreibt nur einen literalen useIntlayer("key")-Aufruf um, der aus dem Framework-Paket importiert wurde — hinter einem Wrapper wird nichts gebündelt.

Deklarieren Sie die Variante stattdessen einmal am Provider, genau wie locale:

import { IntlayerProvider } from "react-intlayer";

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

import { IntlayerProvider } from "next-intlayer/server";

export default async function Layout({ children, params }) {
const { locale } = await params;
const schoolType = await getSchoolType();

return (
<IntlayerProvider locale={locale} variant={schoolType}>
{children}
</IntlayerProvider>
);
}

import { IntlayerServerProvider } from "next-intlayer/server";
import { IntlayerClientProvider } from "next-intlayer";

export default async function Layout({ children, params }) {
const { locale } = await params;
const schoolType = await getSchoolType();

return (
  <IntlayerServerProvider locale={locale} variant={schoolType}>
    <IntlayerClientProvider locale={locale} variant={schoolType}>
      {children}
    </IntlayerClientProvider>
  </IntlayerServerProvider>
);
}

import { createApp } from "vue";
import { installIntlayer } from "vue-intlayer";
import App from "./App.vue";

const app = createApp(App);

installIntlayer(app, { locale: "en", variant: schoolType });

app.mount("#app");

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

export let schoolType: string;

setupIntlayer("en", schoolType);
</script>

<slot />

import { IntlayerProvider } from "preact-intlayer";

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

import { IntlayerProvider } from "solid-intlayer";

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

import { ApplicationConfig } from "@angular/core";
import { provideIntlayer } from "angular-intlayer";

export const appConfig: ApplicationConfig = {
providers: [provideIntlayer("en", true, schoolType)],
};

import { installIntlayer } from "vanilla-intlayer";

installIntlayer({ locale: "en", variant: schoolType });

Jeder Wörterbuchzugriff unterhalb des Providers wird nun gegen diese Variante aufgelöst, und ein Selektor an der Aufrufstelle gewinnt immer:

useIntlayer("hero-banner");
// → die Variante des Providers

useIntlayer("hero-banner", { variant: "summer" });
// → "summer" — ersetzt die Provider-Variante, sie wird nicht erweitert

Formen

Die variant-Prop akzeptiert drei Formen:

Präferenzkette

Eine Kette wird von links nach rechts gegen die von jedem Schlüssel deklarierten Einträge geprüft; der erste deklarierte gewinnt. Ist keiner deklariert, wird der implizite Standardeintrag verwendet — genau wie bei einem Einzelwert.

<IntlayerProvider variant={["school1", "school2"]} />
// `hero-banner` deklariert keinen `school1`-Eintrag, aber `school2` → "school2"
// ein Schlüssel, der keinen von beiden deklariert → der Standardeintrag

["black_friday", "summer"] liest sich also als „black friday, falls dieser Schlüssel eine hat, sonst summer, sonst Standard“. Ketten werden auch an der Aufrufstelle akzeptiert:

useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });

Beachten Sie, dass dies das Spiegelbild des Arrays ist, das das variant-Feld einer Inhaltsdatei akzeptiert: dort deklariert ein Array einen Eintrag je Element, hier konsumiert es sie in Prioritätsreihenfolge.

Zuordnung je Schlüssel

Sprechen Sie jeden Wörterbuchschlüssel einzeln an. Der reservierte Eintrag default deckt alle nicht aufgeführten Schlüssel ab:

<IntlayerProvider
  variant={{
    "hero-banner": "school1",
    product: ["school1", "default"],
    default: "base",
  }}
/>

An einem Provider wird ein einfaches Objekt immer als Zuordnung je Schlüssel gelesen, nie als Objektvariante — beide sind strukturell identisch. Um eine Objektvariante global festzulegen, verschachteln Sie sie unter einem Eintrag: variant={{ default: { id: "prod_abc" } }}.

Da die Schlüssel der Zuordnung gegen Ihre deklarierten Wörterbuchschlüssel geprüft werden, ist ein Tippfehler — oder eine direkt geschriebene Objektvariante wie variant={{ id: "prod_abc" }} — ein Compilerfehler.

Lademodus

Objekt-Varianten werden oft verzögert geladen. Setzen Sie importMode im Wörterbuch, um dies zu steuern:

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

export default dictionary;

Siehe Bundle-Optimierung für Details zu den Modi static, dynamic und fetch.

Typische Anwendungsfälle

• A/B-Texttests, gesteuert durch einen Experiment-Schlüssel
• Saisonale oder Werbebanner
• Feature-Flag-gesteuerte Nachrichten
• Locale-spezifische Marketingkampagnen
• Produktspezifische Marketingtexte, die in einem CMS verwaltet werden
• Benutzer- oder kontospezifische Inhalte
• Beliebige Inhalte, die durch eine opake Laufzeit-ID adressiert werden