@intlayer/docs 9.1.0 → 9.1.2

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:
@@ -22,7 +22,13 @@ history:
     changes: "إصدار ميزة المتغيرات"
   - version: 9.1.0
     date: 2026-06-26
-    changes: "أصبح `variant` يقبل سلسلة نصية أو كائنًا — تُعلَن `meta` / السجلات الديناميكية السابقة كمتغيرات كائنية"
+    changes: "تقبل `variant` الآن سلسلة أو كائنًا — تُعلن السجلات الديناميكية أو `meta` السابقة كمتغيرات كائنات"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "تُعرّف المتغيرة فقط المفاتيح التي تتجاوزها؛ بينما تتراجع المتغيرات غير المُعرّفة إلى الإدخال الافتراضي"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "تقبل المزوِّدات خاصية `variant` محيطية؛ وتقبل المحدِّدات سلسلة تفضيل مرتَّبة"
 author: aymericzip
 ---
 
@@ -37,9 +43,9 @@ author: aymericzip
 
 > يحلّ الشكل الكائني محل حقل `meta` السابق. في كل مكان كنت تكتب فيه سابقًا `meta: { id, … }`، اكتب `variant: { id, … }`، وحدّدها بـ `{ variant: { id, … } }`.
 
-## المتغيرات المُسمّاة (النصية)
+## المتغيرات المسماة (سلسلة نصية)
 
-يمثّل كل ملف بديلًا مُسمّى واحدًا. حذف `variant` (أو ضبطه على `"default"`) يجعله البديل الاحتياطي.
+يمثّل كل ملف بديلًا مُسمّى واحدًا. وإغفال `variant` (أو ضبطه على `"default"`) يجعله البديل الاحتياطي.
 
 ```ts fileName="hero-banner.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
 import { t, type Dictionary } from "intlayer";
@@ -77,10 +83,77 @@ const dictionary = {
 export default dictionary;
 ```
 
-### استهلاك المتغيرات المُسمّاة
+### المتغيرات الجزئية
+
+تُعرّف المتغيرة **فقط المفاتيح التي تتجاوزها**؛ ويتم وراثة الباقي من الإدخال الافتراضي.
+
+```ts fileName="hero-banner.summer.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+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;
+```
+
+```tsx
+useIntlayer("hero-banner", { variant: "summer" });
+// → { headline: "Développez plus vite tout l'été", cta: "Commencer" } — تم وراثة `cta`
+
+useIntlayer("hero-banner", { variant: "never-declared" });
+// → الإدخال الافتراضي
+```
+
+لذلك لا تضيف ملف متغيرة إلا عندما تختلف الصياغة بالفعل. يتحول المفتاح إلى `null` فقط عندما يُعرّف متغيرات ولكن دون إدخال افتراضي.
+
+### استخدام المتغيرات المسماة
 
 #### المتغير الافتراضي
 
+```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;
+```
+
 <Tabs group="framework">
   <Tab label="React" value="react">
     ```tsx fileName="Hero.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
@@ -464,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:
@@ -23,6 +23,12 @@ history:
   - version: 9.1.0
     date: 2026-06-26
     changes: "`variant` akzeptiert jetzt einen String oder ein Objekt — die früheren `meta` / dynamischen Datensätze werden als Objekt-Varianten deklariert"
+  - 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
 ---
 
@@ -77,6 +83,37 @@ const dictionary = {
 export default dictionary;
 ```
 
+### Teilvarianten
+
+Eine Variante deklariert **nur die Schlüssel, die sie überschreibt**; der Rest wird vom Standardeintrag geerbt.
+
+```ts fileName="hero-banner.summer.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+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;
+```
+
+```tsx
+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
@@ -464,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: