@intlayer/docs 9.1.1 → 9.1.3

package/docs/ar/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: المتغيرات
 description: استخدم حقل البيانات الوصفية variant في ملفات محتوى Intlayer لإعلان بدائل محتوى مُسمّاة أو منظّمة — اختبارات A/B، لافتات موسمية، نصوص بأعلام الميزات، سجلات CMS، محتوى خاص بالمستخدم — والتبديل بينها في وقت التشغيل دون تغييرات في الشيفرة.
 keywords:
@@ -26,6 +26,9 @@ history:
   - version: 9.1.1
     date: 2026-07-31
     changes: "تُعرّف المتغيرة فقط المفاتيح التي تتجاوزها؛ بينما تتراجع المتغيرات غير المُعرّفة إلى الإدخال الافتراضي"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "تقبل المزوِّدات خاصية `variant` محيطية؛ وتقبل المحدِّدات سلسلة تفضيل مرتَّبة"
 author: aymericzip
 ---
 
@@ -40,6 +43,46 @@ author: aymericzip
 
 > يحلّ الشكل الكائني محل حقل `meta` السابق. في كل مكان كنت تكتب فيه سابقًا `meta: { id, … }`، اكتب `variant: { id, … }`، وحدّدها بـ `{ variant: { id, … } }`.
 
+## المتغيرات المسماة (سلسلة نصية)
+
+يمثّل كل ملف بديلًا مُسمّى واحدًا. وإغفال `variant` (أو ضبطه على `"default"`) يجعله البديل الاحتياطي.
+
+```ts fileName="hero-banner.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+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;
+```
+
+```ts fileName="hero-banner.black-friday.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+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;
+```
+
 ### المتغيرات الجزئية
 
 تُعرّف المتغيرة **فقط المفاتيح التي تتجاوزها**؛ ويتم وراثة الباقي من الإدخال الافتراضي.
@@ -494,6 +537,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## المتغير المحيطي
+
+بعض أبعاد المتغيرات ثابتة طوال الجلسة — المستأجر، ونوع المدرسة، ومستوى الخطة. تُحلّ مرة واحدة، ولا ينبغي لأي مكوّن أن يمررها يدويًا.
+
+> لا تغلّف `useIntlayer` داخل خطّاف خاص بك لحقنها. فتحسين وقت البناء لا يعيد كتابة سوى استدعاء `useIntlayer("key")` الحرفي المستورد من حزمة إطار العمل، لذا لن يُحزَم أي شيء خلف غلاف.
+
+بدلًا من ذلك، صرّح عن المتغير مرة واحدة على المزوِّد، تمامًا مثل `locale`:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+أصبحت كل قراءة قاموس أسفل المزوِّد تُحلّ وفق ذلك المتغير، ويفوز دائمًا المحدِّد الموجود في موضع الاستدعاء:
+
+```tsx
+useIntlayer("hero-banner");
+// → متغير المزوِّد
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — يستبدل متغير المزوِّد ولا يوسّعه
+```
+
+### الأشكال
+
+تقبل خاصية `variant` ثلاثة أشكال:
+
+| الشكل                                                     | المعنى                        |
+| --------------------------------------------------------- | ----------------------------- |
+| `variant="school1"`                                       | متغير مسمّى واحد لكل المفاتيح |
+| `variant={["school1", "default"]}`                        | سلسلة تفضيل مرتَّبة           |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | متغير لكل مفتاح قاموس         |
+
+#### سلسلة التفضيل
+
+تُجرَّب السلسلة من اليسار إلى اليمين مقابل المدخلات التي يصرّح بها كل مفتاح، ويفوز أول مدخل مُصرَّح به. وعندما لا يكون أي منها مُصرَّحًا به، يُستخدم المدخل الافتراضي الضمني — تمامًا كما في حالة القيمة المفردة.
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` لا يصرّح بمدخل `school1` لكنه يصرّح بـ `school2` ← "school2"
+// مفتاح لا يصرّح بأي منهما ← المدخل الافتراضي
+```
+
+لذا تُقرأ `["black_friday", "summer"]` على أنها «black friday إن كان لهذا المفتاح واحد، وإلا summer، وإلا الافتراضي». وتُقبل السلاسل أيضًا في موضع الاستدعاء:
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> لاحظ أن هذا هو الصورة المعكوسة للمصفوفة التي يقبلها **حقل** `variant` في ملف المحتوى: فهناك تُصرِّح المصفوفة بمدخل لكل عنصر، أما هنا فتستهلكها بترتيب الأولوية.
+
+#### خريطة لكل مفتاح
+
+خاطب كل مفتاح قاموس على حدة. ويغطي المدخل المحجوز `default` كل المفاتيح غير المذكورة:
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> على المزوِّد، يُقرأ الكائن البسيط **دائمًا** كخريطة لكل مفتاح، ولا يُقرأ أبدًا كمتغير كائني — فالاثنان متطابقان بنيويًا. ولتثبيت متغير كائني عالميًا، ضعه متداخلًا تحت مدخل: `variant={{ default: { id: "prod_abc" } }}`.
+
+ولأن مفاتيح الخريطة تُدقَّق مقابل مفاتيح القواميس المصرَّح بها، فإن أي خطأ مطبعي — أو متغيرًا كائنيًا مكتوبًا مباشرة مثل `variant={{ id: "prod_abc" }}` — يُعدّ خطأ في وقت الترجمة.
+
 ## وضع التحميل
 
 غالبًا ما تُحمَّل المتغيرات الكائنية بشكل كسول. اضبط `importMode` على القاموس للتحكم في ذلك:

package/docs/de/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: Varianten
 description: Verwenden Sie das variant-Metadatenfeld in Intlayer-Inhaltsdateien, um benannte oder strukturierte Inhaltsalternativen zu deklarieren — A/B-Tests, saisonale Banner, Feature-Flag-Texte, CMS-Datensätze, benutzerspezifische Inhalte — und zur Laufzeit ohne Codeänderungen zwischen ihnen zu wechseln.
 keywords:
@@ -26,6 +26,9 @@ history:
   - version: 9.1.1
     date: 2026-07-31
     changes: "Eine Variante deklariert nur die Schlüssel, die sie überschreibt; nicht deklarierte Varianten fallen auf den Standardeintrag zurück"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "Provider akzeptieren eine ambiente `variant`-Prop; Selektoren akzeptieren eine geordnete Präferenzkette"
 author: aymericzip
 ---
 
@@ -498,6 +501,176 @@ const content = useIntlayer("product", {
 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`:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+Jeder Wörterbuchzugriff unterhalb des Providers wird nun gegen diese Variante aufgelöst, und ein Selektor an der Aufrufstelle gewinnt immer:
+
+```tsx
+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:
+
+| Form                                                      | Bedeutung                                  |
+| --------------------------------------------------------- | ------------------------------------------ |
+| `variant="school1"`                                       | eine benannte Variante für jeden Schlüssel |
+| `variant={["school1", "default"]}`                        | eine geordnete Präferenzkette              |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | eine Variante pro Wörterbuchschlüssel      |
+
+#### 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.
+
+```tsx
+<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:
+
+```tsx
+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:
+
+```tsx
+<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:

package/docs/en/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-07-31
+updatedAt: 2026-08-04
 title: Variants
 description: Use the variant metadata field in Intlayer content files to declare named or structured content alternatives — A/B tests, seasonal banners, feature-flagged copy, CMS records, user-specific content — and switch between them at runtime without code changes.
 keywords:
@@ -26,6 +26,9 @@ history:
   - version: 9.1.1
     date: 2026-07-31
     changes: "A variant declares only the keys it overrides; undeclared variants fall back to the default entry"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "Providers accept an ambient `variant` prop; selectors accept an ordered preference chain"
 author: aymericzip
 ---
 
@@ -498,6 +501,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## Ambient variant
+
+Some variant dimensions are fixed for a whole session — the tenant, the school type, the plan tier. They are resolved once, and no component should have to pass them by hand.
+
+> Do not wrap `useIntlayer` in your own hook to inject them. The build-time optimization only rewrites a literal `useIntlayer("key")` imported from the framework package, so nothing behind a wrapper gets bundled.
+
+Declare the variant once on the provider instead, exactly like `locale`:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "react-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>
+      );
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```ts fileName="main.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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");
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="+layout.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script lang="ts">
+    import { setupIntlayer } from "svelte-intlayer";
+
+    export let schoolType: string;
+
+    setupIntlayer("en", schoolType);
+    </script>
+
+    <slot />
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "preact-intlayer";
+
+    export const App = ({ locale, schoolType }) => (
+      <IntlayerProvider locale={locale} variant={schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="App.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { IntlayerProvider } from "solid-intlayer";
+
+    export const App = (props) => (
+      <IntlayerProvider locale={props.locale} variant={props.schoolType}>
+        <Hero />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="app.config.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { ApplicationConfig } from "@angular/core";
+    import { provideIntlayer } from "angular-intlayer";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer("en", true, schoolType)],
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="main.js"
+    import { installIntlayer } from "vanilla-intlayer";
+
+    installIntlayer({ locale: "en", variant: schoolType });
+    ```
+
+  </Tab>
+</Tabs>
+
+Every dictionary read below the provider now resolves against that variant, and a call-site selector always wins:
+
+```tsx
+useIntlayer("hero-banner");
+// → the provider variant
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — replaces the provider variant, it is not extended
+```
+
+### Forms
+
+The `variant` prop accepts three forms:
+
+| Form                                                      | Meaning                         |
+| --------------------------------------------------------- | ------------------------------- |
+| `variant="school1"`                                       | one named variant for every key |
+| `variant={["school1", "default"]}`                        | an ordered preference chain     |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | one variant per dictionary key  |
+
+#### Preference chain
+
+A chain is tried left to right against the entries each key declares, and the first declared one wins. When none is declared, the implicit default entry is used — exactly as for a single value.
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` declares no `school1` entry but declares `school2` → "school2"
+// a key declaring neither                                          → the default entry
+```
+
+So `["black_friday", "summer"]` reads as "black friday if this key has one, else summer, else default". Chains are also accepted at the call site:
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> Note this is the mirror image of the array accepted by the `variant` **field** of a content file: there an array _declares_ one entry per element, here it _consumes_ them in priority order.
+
+#### Per-key map
+
+Address each dictionary key separately. The reserved `default` entry covers every key not listed:
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> On a provider a plain object is **always** read as the per-key map, never as an object variant — the two are structurally identical. To pin an object variant globally, nest it under an entry: `variant={{ default: { id: "prod_abc" } }}`.
+
+Because the map's keys are checked against your declared dictionary keys, a typo — or an object variant written directly, such as `variant={{ id: "prod_abc" }}` — is a compile-time error.
+
 ## Loading mode
 
 Object variants are often loaded lazily. Set `importMode` on the dictionary to control this: