@intlayer/docs 9.0.0-canary.7 → 9.0.0-canary.8

package/docs/tr/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Varyantlar
-description: Kod değişikliği yapmadan çalışma zamanında aralarında geçiş yapmak üzere adlandırılmış içerik alternatiflerini — A/B testleri, dönemsel afişler, özellik bayraklı (feature flag) metinler — bildirmek için Intlayer içerik dosyalarındaki variant meta veri alanını kullanın.
+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:
   - Varyantlar
   - A/B Testi
   - Özellik Bayrakları
   - Dinamik İçerik
+  - Dinamik Kayıtlar
+  - CMS
   - Intlayer
   - Uluslararasılaştırma
 slugs:
@@ -17,17 +19,27 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "Varyantlar özelliğinin sürümü"
+    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"
 author: aymericzip
 ---
 
 # Varyantlar
 
-Bir **varyant** (variant), aynı sözlük anahtarını (`key`) paylaşan ancak her biri farklı bir `variant` adı taşıyan içerik dosyaları kümesidir. Intlayer, `useIntlayer` fonksiyonuna geçirilen seçiciye göre uygun dosyayı sunar.
+Bir **varyant**, aynı sözlük anahtarını (`key`) paylaşan ancak her biri farklı bir `variant` değeri taşıyan bir içerik dosyaları kümesidir. Intlayer, `useIntlayer`'a geçirilen seçiciye göre uygun dosyayı sunar.
 
-## Varyantları bildirme
+`variant` değeri **iki biçim** alabilir:
 
-Her dosya adlandırılmış bir alternatifi temsil eder. `variant` alanının atlanması (veya `"default"` olarak ayarlanması) onu varsayılan (fallback) varyant olarak işaretler.
+- **Bir dize** — tek bir adlandırılmış alternatif (A/B testleri, sezonluk afişler, özellik bayrakları).
+- **Bir nesne** — bir alan kümesiyle adreslenen yapılandırılmış bir ayırt edici (CMS kayıtları, kullanıcıya özel metin, opak bir kimlikle anahtarlanan herhangi bir içerik). Kimlik nesnenin tamamıdır: seçici, girdiyi çözümlemek için **eşit** bir nesne sağlamalıdır.
+
+> Nesne biçimi eski `meta` alanının yerini alır. Daha önce `meta: { id, … }` yazdığınız her yerde `variant: { id, … }` yazın ve onu `{ variant: { id, … } }` ile seçin.
+
+## Adlandırılmış (dize) varyantlar
+
+Her dosya bir adlandırılmış alternatifi temsil eder. `variant`'ı atlamak (veya `"default"` olarak ayarlamak) onu yedek olarak işaretler.
 
 ```ts fileName="hero-banner.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
 import { t, type Dictionary } from "intlayer";
@@ -65,9 +77,9 @@ const dictionary = {
 export default dictionary;
 ```
 
-## Varyantları tüketme
+### Adlandırılmış varyantları kullanma
 
-### Varsayılan varyant
+#### Varsayılan varyant
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Adlandırılmış varyant
+#### Adlandırılmış varyant
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Belirli dil seçeneği ile adlandırılmış varyant
+#### Açık locale ile adlandırılmış varyant
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "tr",
+  locale: "fr",
 });
 ```
 
-## Tipik kullanım senaryoları
+## Nesne (yapılandırılmış) varyantlar
+
+Bir nesne varyantı, `variant` alanında bildirilen rastgele bir anahtar-değer çiftleri kümesiyle içeriği adresler — bu da CMS kayıtlarını, kullanıcıya özel metni veya anahtarı opak bir kimlik olan herhangi bir içeriği modellemeyi mümkün kılar. Kimlik **nesnenin tamamıdır**: girdinin çözümlenmesi için seçici eşit bir nesne sağlamalıdır.
+
+```ts fileName="product.abc.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+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;
+```
+
+```ts fileName="product.abcd.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+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;
+```
+
+### Nesne varyantlarını kullanma
+
+Eşleşen nesneyi `variant`'a geçirin. Sözlükte bildirilen her alan sağlanmalı ve eşit olmalıdır; aksi takdirde sonuç `null` olur. Alanların sırası önemli değildir.
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```vue fileName="Product.vue" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <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>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="Product.svelte" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <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}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="Product.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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>}
+        </>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="product.component.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    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 },
+        });
+      }
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="product.js"
+    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>`;
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+#### Açık locale ile
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Eksik alan — eşleşme yok
+
+```ts
+// null döndürür: `userId` eksik, bu nedenle nesne bildirilen varyantla eşleşmiyor
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Yükleme modu
+
+Nesne varyantları genellikle tembel olarak yüklenir. Bunu kontrol etmek için sözlükte `importMode`'u ayarlayın:
+
+```ts contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+const dictionary = {
+  key: "product",
+  importMode: "fetch", // or "dynamic"
+  variant: { id: "prod_abc", userId: "user_123" },
+  content: { … },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+`static`, `dynamic` ve `fetch` modlarıyla ilgili ayrıntılar için [paket optimizasyonu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/bundle_optimization.md) bölümüne bakın.
+
+## Tipik kullanım örnekleri
 
-- Bir deney anahtarı (experiment key) tarafından yönlendirilen A/B metin testleri
-- Dönemsel veya tanıtım afişleri
-- Özellik bayraklı (feature flag) mesajlaşma
-- Bölgeye özel pazarlama kampanyaları
+- Bir deney anahtarıyla yönlendirilen A/B metin testleri
+- Sezonluk veya promosyon afişleri
+- Özellik bayraklı mesajlaşma
+- Locale'e özgü pazarlama kampanyaları
+- CMS'te yönetilen ürün başına pazarlama metni
+- Kullanıcıya veya hesaba özel içerik
+- Çalışma zamanında opak bir kimlikle anahtarlanan herhangi bir içerik

package/docs/tr/plugins/sync-json.md

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * Çıktıyı ve çevirileri locales dizinindeki JSON dosyalarına yükleyecek ve yazacaktır
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/tr/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: Yeni Intlayer v9 - Yenilikler Neler?
-description: Intlayer v9'daki yenilikleri keşfedin. Popüler i18n kütüphaneleri için doğrudan uyumlu paketler ve Koleksiyonlar, Varyantlar ve Dinamik Kayıtlar desteği sunuluyor.
+description: Intlayer v9'daki yenilikleri keşfedin. Popüler i18n kütüphaneleri için doğrudan uyumlu paketler ve Koleksiyonlar ve Varyantlar desteği sunuluyor.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # Yeni Intlayer v9 - Yenilikler Neler?
 
-Intlayer v9'a hoş geldiniz! Bu ana sürüm, büyük i18n kütüphaneleri (`react-i18next`, `next-intl`, `vue-i18n` vb.) için sunulan **Compat Adapter Paketleri** ile Intlayer'a geçiş sürecini basitleştirmede dev bir adımı temsil ediyor ve zengin içerik yapıları için destek ekliyor: **Koleksiyonlar (Collections)**, **Varyantlar (Variants)** ve **Dinamik Kayıtlar (Dynamic Records)**.
+Intlayer v9'a hoş geldiniz! Bu ana sürüm, büyük i18n kütüphaneleri (`react-i18next`, `next-intl`, `vue-i18n` vb.) için sunulan **Compat Adapter Paketleri** ile Intlayer'a geçiş sürecini basitleştirmede dev bir adımı temsil ediyor ve zengin içerik yapıları için destek ekliyor: **Koleksiyonlar (Collections)** ve **Varyantlar (Variants)**.
 
 ## İçindekiler
 
@@ -41,8 +40,10 @@ Popüler i18n kütüphanelerinden Intlayer'a geçiş yapmak artık her zamankind
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 Örneğin, sadece şunu değiştirin:
 
@@ -100,7 +101,7 @@ Tüm compat adapter'lar artık çeviri çözümlemesini tek ve son derece optimi
 
 ---
 
-## Özellik Detayları: Koleksiyonlar, Varyantlar ve Dinamik Kayıtlar
+## Özellik Detayları: Koleksiyonlar ve Varyantlar
 
 Intlayer v9, statik anahtar-değer nesnelerinin ötesine geçerek sözlüklerin uçtan uca tam tiplendirilmiş dinamik düzen yapıları tanımlamasına olanak tanır.
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 A/B testleri, mevsimsel başlıklar, özellik bayrakları (feature flags) veya özel açılış sayfaları sunun:
 
+#### Dize varyantları (örneğin, A/B testleri)
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -167,16 +170,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. Dinamik Kayıtlar (Dynamic Records)
-
-Girdileri çalışma zamanında sorgu kimlikleri (query IDs) aracılığıyla dinamik olarak yüklenen sözlükler tanımlayın:
+#### Nesne varyantları (örneğin, Dinamik Kayıtlar)
 
 ```ts fileName="product.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "product-copy",
-  meta: {
+  variant: {
     id: "prod_123",
     category: "books",
   },
@@ -229,7 +230,7 @@ export default defineConfig({
 });
 ```
 
-- **Compiler**: `compiler.enabled` ayarlandığında ve `compiler.output` yolu yapılandırıldığında otomatik olarak etkinleştirilir. Artık `intlayerCompiler()`'ı ayrı olarak kaydetmeniz gerekmez.
+- **Compiler**: `compiler.enabled` `true` olarak ayarlandığında ve `compiler.output` yolu yapılandırıldığında otomatik olarak etkinleştirilir. Artık `intlayerCompiler()`'ı ayrı olarak kaydetmeniz gerekmez.
 - **Proxy**: Yeni `routing.enableProxy` seçeneğine göre otomatik olarak etkinleştirilir (varsayılan olarak `true`). Geliştirme, önizleme ve üretim SSR'de locale algılama / yönlendirme / yeniden yazma middleware'ini bağlar. Artık `intlayerProxy()`'ı ayrı olarak kaydetmeniz gerekmez.
 
 ### `routing.enableProxy` seçeneği
@@ -252,6 +253,27 @@ Bağımsız `intlayerCompiler()` ve `intlayerProxy()` eklentileri gelişmiş kur
 
 ---
 
+## Derleyici varsayılan olarak devre dışı
+
+Intlayer v9'dan itibaren, **derleyici varsayılan olarak devre dışıdır** (`compiler.enabled` artık varsayılan olarak `false`'tur). `.content.ts` dosyalarınızın derleme zamanı çıkarımını etkinleştirmek için yapılandırmanızda `compiler.enabled: true` olarak ayarlayın:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Varsayılan: false — v9'dan itibaren derleyiciyi etkinleştirmek için gereklidir
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Derleyici devre dışı bırakıldığında, Intlayer derleme zamanı çıkarım adımını atlar ve önceden bildirdiğiniz sözlüklere dayanır. Yalnızca bundler eklentisinin (`@intlayer/swc`, `@intlayer/babel` veya `intlayer()` Vite eklentisi) içeriği otomatik olarak çıkarmasını istediğinizde etkinleştirin.
+
+---
+
 ## React Native: tek paket içe aktarmaları
 
 Bir React Native veya Expo uygulamasında, artık `react-intlayer` ve `react-native-intlayer` arasında gidip gelmenize gerek yok. `react-native-intlayer` paketi artık **tüm `react-intlayer` API'sini yeniden dışa aktarıyor** (hook'lar, yardımcı programlar ve `/format`, `/html` ve `/markdown` alt yolları) ve `IntlayerProvider`'ı React Native polyfill'lerini otomatik olarak uyguluyor.
@@ -278,13 +300,14 @@ npm install intlayer react-native-intlayer
 
 v8'den yükseltme yapıyorsanız, v9'un yıkıcı değişiklikler (breaking changes) içermediğini unutmayın. Ancak işte temel değişiklikler:
 
+- **Derleyici varsayılan olarak devre dışı**: `compiler.enabled` artık varsayılan olarak `false`'tur. `.content.ts` dosyalarınızın derleme zamanı çıkarımına güveniyorsanız, `intlayer.config.ts` dosyanızda `compiler.enabled: true` olarak ayarlayın.
 - **Diller ve Lehçeler (Locales & Dialects)**: Harici i18n bağımlılıkları kullanıyorsanız, içe aktarmaları otomatik olarak yeniden yazmak için yapılandırmanıza veya bundler kurulumunuza ilgili compat adapter eklentilerini ekleyin.
-- **Özel Seçiciler (Custom Selectors)**: `useIntlayer` çağrılırken, ikinci parametre artık `{ locale, item, variant, id }` içeren bir seçenek nesnesine ayrılmıştır. Daha önce doğrudan bir dil (locale) dizesi geçirdiyseniz bunu yapmaya devam edebilirsiniz, ancak gelişmiş seçimler için seçenekler nesnesini kullanmanız önerilir.
+- **Özel Seçiciler (Custom Selectors)**: `useIntlayer` çağrılırken, ikinci parametre artık `{ locale, item, variant }` içeren bir seçenek nesnesine ayrılmıştır. Daha önce doğrudan bir dil (locale) dizesi geçirdiyseniz bunu yapmaya devam edebilirsiniz, ancak gelişmiş seçimler için seçenekler nesnesini kullanmanız önerilir.
 
 ---
 
 ## Faydalı bağlantılar
 
 - [Compat Adapter Paketleri Kılavuzu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/compat/index.md)
-- [Dinamik Sözlükler - Koleksiyonlar, Varyantlar ve Dinamik Kayıtlar](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/dynamic_dictionaries/index.md)
+- [Dinamik Sözlükler - Koleksiyonlar ve Varyantlar](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/dynamic_dictionaries/index.md)
 - [Yapılandırma Referansı](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/configuration.md)

package/docs/uk/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Динамічні Словники
-description: Огляд трьох функцій динамічних словників Intlayer — колекцій, варіантів та динамічних записів — для створення гнучкого вмісту i18n, керованого під час виконання.
+updatedAt: 2026-06-26
+title: Динамічні словники
+description: Огляд можливостей динамічних словників Intlayer — колекцій і варіантів — для створення гнучкого i18n-контенту, керованого під час виконання.
 keywords:
-  - Динамічні Словники
+  - Динамічні словники
   - Колекції
   - Варіанти
-  - Динамічні Записи
   - Intlayer
   - Інтернаціоналізація
 slugs:
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "Випуск функції динамічних словників"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Динамічні записи об'єднано з варіантами — `variant` тепер приймає рядок або об'єкт"
 author: aymericzip
 ---
 
-# Динамічні Словники
+# Динамічні словники
 
-Intlayer підтримує три механізми для представлення вмісту, що виходить за межі одного статичного словника на ключ. Кожен з них оголошується через **поле метаданих верхнього рівня** у файлі вмісту; жодна функція-обгортка (wrapper) не потрібна.
+Intlayer підтримує два механізми для вираження контенту, що виходить за межі єдиного статичного словника на ключ. Кожен оголошується через **поле метаданих верхнього рівня** у файлі контенту; функція-обгортка не потрібна.
 
-| Функція                                                                                                                   | Поле метаданих    | Селектор в `useIntlayer` |
-| ------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------ |
-| [Колекції](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/collections.md)             | `item: N`         | `{ item: N }`            |
-| [Варіанти](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/variants.md)                | `variant: "name"` | `{ variant: "name" }`    |
-| [Динамічні Записи](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`              |
+| Можливість                                                                                                    | Поле метаданих                           | Селектор у `useIntlayer`                         |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ |
+| [Колекції](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/collections.md) | `item: N`                                | `{ item: N }`                                    |
+| [Варіанти](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/variants.md)    | `variant: "name"` _або_ `variant: { … }` | `{ variant: "name" }` _або_ `{ variant: { … } }` |
 
-Усі три механізми поєднуються з аргументом локалі та підтримують вибіркове / ледаче завантаження (lazy loading) за допомогою `importMode`.
+Обидва поєднуються з аргументом locale і підтримують вибіркове / відкладене завантаження через `importMode`.
 
 ## Коли що використовувати
 
-- **Колекції** — упорядкований список елементів, керованих в окремих файлах (елементи FAQ, повідомлення в блогах, продукти).
-- **Варіанти** — іменовані альтернативи вмісту для A/B-тестів, сезонних банерів або прапорців функцій (feature flags).
-- **Динамічні записи** — вміст, що отримується під час виконання за непрозорим ідентифікатором ID (записи CMS, вміст конкретного користувача).
+- **Колекції** — упорядкований список елементів, керованих в окремих файлах (записи FAQ, пости блогу, товари).
+- **Варіанти** — іменовані або структуровані альтернативи контенту:
+  - **рядковий** варіант для A/B-тестів, сезонних банерів або feature-прапорців;
+  - **об'єктний** варіант для записів CMS, контенту конкретного користувача або будь-якого контенту, адресованого набором полів (колишні «динамічні записи»).
 
-## Вирішення конфліктів селекторів
+> У попередніх версіях для контенту за записами було окреме поле `meta`. Його об'єднано з `variant`: передавайте `variant` **об'єкт** замість використання `meta`.
 
-Коли у словнику є кілька селекторів, порядок вирішення наступний:
+## Усунення неоднозначності селектора
+
+Ключ може оголошувати обидва виміри одночасно (наприклад, колекція, кожен елемент якої має варіант). Вони розв'язуються в порядку:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+Отже, `{ variant: "promo" }` для ключа variant × item повертає всі promo-елементи як масив, а додавання `{ item: 2 }` звужує результат до одного запису.