@intlayer/docs 9.1.0 → 9.1.2

package/docs/tr/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-26
+updatedAt: 2026-08-04
 title: Varyantlar
 description: Adlandırılmış veya yapılandırılmış içerik alternatifleri — A/B testleri, sezonluk afişler, özellik bayraklı metin, CMS kayıtları, kullanıcıya özel içerik — bildirmek ve kod değişikliği olmadan çalışma zamanında aralarında geçiş yapmak için Intlayer içerik dosyalarında variant meta veri alanını kullanın.
 keywords:
@@ -22,7 +22,13 @@ history:
     changes: "Varyantlar özelliğinin yayımlanması"
   - version: 9.1.0
     date: 2026-06-26
-    changes: "`variant` artık bir dize veya nesne kabul ediyor — eski `meta` / dinamik kayıtlar nesne varyantı olarak bildirilir"
+    changes: "`variant` artık bir dize veya bir nesne kabul ediyor — önceki `meta` / dinamik kayıtlar nesne varyantları olarak bildiriliyor"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "Bir varyant yalnızca geçersiz kıldığı anahtarları bildirir; bildirilmemiş varyantlar varsayılan girdiye geri döner"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "Sağlayıcılar ortam düzeyinde bir `variant` prop'u kabul eder; seçiciler sıralı bir tercih zinciri kabul eder"
 author: aymericzip
 ---
 
@@ -77,6 +83,37 @@ const dictionary = {
 export default dictionary;
 ```
 
+### Kısmi varyantlar
+
+Bir varyant **yalnızca geçersiz kıldığı anahtarları bildirir**; geri kalanı varsayılan girdiden miras alınır.
+
+```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` miras alındı
+
+useIntlayer("hero-banner", { variant: "never-declared" });
+// → varsayılan girdi
+```
+
+Böylece yalnızca ifadelerin gerçekten farklı olduğu durumlarda bir varyant dosyası eklersiniz. Bir anahtar, yalnızca varyantları bildirip varsayılan girdisi olmadığında `null` olarak çözülür.
+
 ### Adlandırılmış varyantları kullanma
 
 #### Varsayılan varyant
@@ -464,6 +501,176 @@ const content = useIntlayer("product", {
 const content = useIntlayer("product", { variant: { id: "prod_abc" } });
 ```
 
+## Ortam varyantı
+
+Bazı varyant boyutları tüm oturum boyunca sabittir — kiracı, okul türü, plan seviyesi. Bir kez çözümlenirler ve hiçbir bileşenin bunları elle geçirmesi gerekmemelidir.
+
+> Bunları enjekte etmek için `useIntlayer`'ı kendi hook'unuza sarmayın. Derleme zamanı optimizasyonu yalnızca framework paketinden içe aktarılan düz bir `useIntlayer("key")` çağrısını yeniden yazar; bir sarmalayıcının arkasındaki hiçbir şey paketlenmez.
+
+Bunun yerine varyantı sağlayıcıda bir kez bildirin, tıpkı `locale` gibi:
+
+<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>
+
+Sağlayıcının altındaki her sözlük okuması artık bu varyanta göre çözümlenir ve çağrı noktasındaki bir seçici her zaman kazanır:
+
+```tsx
+useIntlayer("hero-banner");
+// → sağlayıcının varyantı
+
+useIntlayer("hero-banner", { variant: "summer" });
+// → "summer" — sağlayıcı varyantının yerini alır, onu genişletmez
+```
+
+### Biçimler
+
+`variant` prop'u üç biçim kabul eder:
+
+| Biçim                                                     | Anlamı                                         |
+| --------------------------------------------------------- | ---------------------------------------------- |
+| `variant="school1"`                                       | her anahtar için tek bir adlandırılmış varyant |
+| `variant={["school1", "default"]}`                        | sıralı bir tercih zinciri                      |
+| `variant={{ "hero-banner": "school1", default: "base" }}` | sözlük anahtarı başına bir varyant             |
+
+#### Tercih zinciri
+
+Zincir, her anahtarın bildirdiği girdilere karşı soldan sağa denenir ve bildirilen ilk girdi kazanır. Hiçbiri bildirilmemişse örtük varsayılan girdi kullanılır — tıpkı tek bir değerde olduğu gibi.
+
+```tsx
+<IntlayerProvider variant={["school1", "school2"]} />
+// `hero-banner` bir `school1` girdisi bildirmez ama `school2` bildirir → "school2"
+// ikisini de bildirmeyen bir anahtar → varsayılan girdi
+```
+
+Yani `["black_friday", "summer"]` şöyle okunur: «bu anahtarda varsa black friday, yoksa summer, o da yoksa varsayılan». Zincirler çağrı noktasında da kabul edilir:
+
+```tsx
+useIntlayer("hero-banner", { variant: ["black_friday", "summer"] });
+```
+
+> Bunun, bir içerik dosyasının `variant` **alanının** kabul ettiği dizinin ayna görüntüsü olduğuna dikkat edin: orada bir dizi öğe başına bir girdi _bildirir_, burada ise onları öncelik sırasına göre _tüketir_.
+
+#### Anahtar başına eşleme
+
+Her sözlük anahtarını ayrı ayrı adresleyin. Ayrılmış `default` girdisi, listelenmeyen tüm anahtarları kapsar:
+
+```tsx
+<IntlayerProvider
+  variant={{
+    "hero-banner": "school1",
+    product: ["school1", "default"],
+    default: "base",
+  }}
+/>
+```
+
+> Bir sağlayıcıda düz bir nesne **her zaman** anahtar başına eşleme olarak okunur, asla nesne varyantı olarak değil — ikisi yapısal olarak aynıdır. Bir nesne varyantını global olarak sabitlemek için onu bir girdinin altına yerleştirin: `variant={{ default: { id: "prod_abc" } }}`.
+
+Eşlemenin anahtarları bildirdiğiniz sözlük anahtarlarına karşı denetlendiğinden, bir yazım hatası — ya da doğrudan yazılmış bir nesne varyantı, örneğin `variant={{ id: "prod_abc" }}` — derleme zamanı hatasıdır.
+
 ## Yükleme modu
 
 Nesne varyantları genellikle tembel olarak yüklenir. Bunu kontrol etmek için sözlükte `importMode`'u ayarlayın:

package/docs/uk/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-тести, сезонні банери, тексти під feature-прапорцями, записи CMS, контент конкретного користувача — і перемикатися між ними під час виконання без змін коду.
 keywords:
@@ -23,6 +23,12 @@ history:
   - version: 9.1.0
     date: 2026-06-26
     changes: "`variant` тепер приймає рядок або об'єкт — колишні `meta` / динамічні записи оголошуються як об'єктні варіанти"
+  - version: 9.1.1
+    date: 2026-07-31
+    changes: "Варіант оголошує лише ключі, які він перевизначає; неоголошені варіанти повертаються до запису за замовчуванням"
+  - version: 9.1.2
+    date: 2026-08-04
+    changes: "Провайдери приймають зовнішній проп `variant`; селектори приймають упорядкований ланцюжок переваг"
 author: aymericzip
 ---
 
@@ -77,6 +83,37 @@ 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` тільки в тому випадку, якщо він оголошує варіанти, але не має запису за замовчуванням.
+
 ### Використання іменованих варіантів
 
 #### Варіант за замовчуванням
@@ -464,6 +501,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` у словнику, щоб керувати цим: