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

package/docs/uk/dynamic_dictionaries/variants.md

@@ -1,13 +1,15 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: Варіанти
-description: Використовуйте поле метаданих variant у файлах вмісту Intlayer для оголошення іменованих альтернатив вмісту (A/B-тести, сезонні банери, тексти з прапорцями функцій) і перемикання між ними під час виконання без зміни коду.
+description: Використовуйте поле метаданих variant у файлах контенту Intlayer, щоб оголошувати іменовані або структуровані альтернативи контенту — A/B-тести, сезонні банери, тексти під feature-прапорцями, записи CMS, контент конкретного користувача — і перемикатися між ними під час виконання без змін коду.
 keywords:
   - Варіанти
-  - A/B Тестування
-  - Прапорці Функцій
-  - Динамічний Вміст
+  - A/B-тестування
+  - Feature-прапорці
+  - Динамічний контент
+  - Динамічні записи
+  - CMS
   - Intlayer
   - Інтернаціоналізація
 slugs:
@@ -17,17 +19,27 @@ slugs:
 history:
   - version: 9.0.0
     date: 2026-06-12
-    changes: "Випуск функції варіантів словників"
+    changes: "Випуск функції варіантів"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "`variant` тепер приймає рядок або об'єкт — колишні `meta` / динамічні записи оголошуються як об'єктні варіанти"
 author: aymericzip
 ---
 
 # Варіанти
 
-**Варіант** (Variant) — це набір файлів вмісту, які мають спільний ключ словника (`key`), але кожен має власну назву варіанта (`variant`). Intlayer надає відповідний файл на основі селектора, переданого в `useIntlayer`.
+**Варіант** — це набір файлів контенту, що мають спільний ключ словника (`key`), але кожен несе своє значення `variant`. Intlayer віддає відповідний файл на основі селектора, переданого до `useIntlayer`.
 
-## Оголошення варіантів
+Значення `variant` може набувати **двох форм**:
 
-Кожен файл представляє одну іменовану альтернативу. Опущення `variant` (або встановлення значення `"default"`) позначає його як варіант за замовчуванням (fallback).
+- **Рядок** — одна іменована альтернатива (A/B-тести, сезонні банери, feature-прапорці).
+- **Об'єкт** — структурований дискримінатор, адресований набором полів (записи CMS, контент конкретного користувача, будь-який контент із непрозорим ID як ключем). Ідентичністю є весь об'єкт: селектор має надати **рівний** об'єкт, щоб розв'язати запис.
+
+> Об'єктна форма замінює колишнє поле `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";
@@ -65,9 +77,9 @@ const dictionary = {
 export default dictionary;
 ```
 
-## Використання варіантів
+### Використання іменованих варіантів
 
-### Варіант за замовчуванням
+#### Варіант за замовчуванням
 
 <Tabs group="framework">
   <Tab label="React" value="react">
@@ -209,7 +221,7 @@ export default dictionary;
   </Tab>
 </Tabs>
 
-### Іменований варіант
+#### Іменований варіант
 
 ```tsx
 const { headline, cta } = useIntlayer("hero-banner", {
@@ -217,18 +229,264 @@ const { headline, cta } = useIntlayer("hero-banner", {
 });
 ```
 
-### Іменований варіант із явною локаллю
+#### Іменований варіант із явною локаллю
 
 ```tsx
 const content = useIntlayer("hero-banner", {
   variant: "black_friday",
-  locale: "uk",
+  locale: "fr",
 });
 ```
 
-## Типові варіанти використання
+## Об'єктні (структуровані) варіанти
+
+Об'єктний варіант адресує контент довільним набором пар ключ-значення, оголошених у полі `variant`, — що дозволяє моделювати записи CMS, контент конкретного користувача або будь-який контент із непрозорим ID як ключем. Ідентичністю є **весь об'єкт**: селектор має надати рівний об'єкт, щоб запис було розв'язано.
+
+```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;
+```
+
+### Використання об'єктних варіантів
+
+Передайте відповідний об'єкт у `variant`. Кожне поле, оголошене у словнику, має бути надане й рівне; інакше результат — `null`. Порядок полів не має значення.
+
+<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>
+
+#### З явною локаллю
+
+```tsx
+const content = useIntlayer("product", {
+  variant: { id: "prod_abc", userId: "user_123" },
+  locale: "fr",
+});
+```
+
+#### Відсутнє поле — немає збігу
+
+```ts
+// Повертає null: відсутній `userId`, тож об'єкт не збігається з оголошеним варіантом
+const content = useIntlayer("product", { variant: { id: "prod_abc" } });
+```
+
+## Режим завантаження
+
+Об'єктні варіанти часто завантажуються ліниво. Задайте `importMode` у словнику, щоб керувати цим:
+
+```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;
+```
+
+Див. [оптимізацію бандла](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/bundle_optimization.md) для деталей про режими `static`, `dynamic` і `fetch`.
+
+## Типові сценарії використання
 
-- A/B-тестування текстів, кероване ключем експерименту
-- Сезонні або промо-банери
-- Повідомлення, керовані прапорцями функцій (feature flags)
-- Маркетингові кампанії для конкретних регіонів
+- A/B-тести тексту, керовані ключем експерименту
+- Сезонні або рекламні банери
+- Повідомлення під feature-прапорцями
+- Маркетингові кампанії для конкретної локалі
+- Маркетинговий текст за товарами, керований у CMS
+- Контент конкретного користувача або акаунта
+- Будь-який контент, адресований непрозорим ID під час виконання

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

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * Завантажить та запише результати й переклади назад у JSON-файли в директорії locales
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/uk/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-25
+updatedAt: 2026-06-26
 title: Новий Intlayer v9 - Що нового?
-description: Дізнайтеся, що нового в Intlayer v9. Представляємо сумісні пакети швидкої заміни (drop-in) для популярних бібліотек i18n та підтримку Collections, Variants та Dynamic Records.
+description: Дізнайтеся, що нового в Intlayer v9. Представляємо сумісні пакети швидкої заміни (drop-in) для популярних бібліотек i18n та підтримку Collections та Variants.
 keywords:
   - Intlayer
   - Сумісність
   - Міграція
   - Колекції
   - Варіанти
-  - Динамічні записи
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # Новий Intlayer v9 - Що нового?
 
-Ласкаво просимо до Intlayer v9! Цей мажорний реліз є величезною віхою у спрощенні шляху міграції на Intlayer завдяки **Compat Adapter Packages** (пакетам адаптерів сумісності) для основних бібліотек i18n (`react-i18next`, `next-intl`, `vue-i18n` тощо) та додає підтримку складних структур контенту: **Collections** (Колекцій), **Variants** (Варіантів) та **Dynamic Records** (Динамічних записів).
+Ласкаво просимо до Intlayer v9! Цей мажорний реліз є величезною віхою у спрощенні шляху міграції на Intlayer завдяки **Compat Adapter Packages** (пакетам адаптерів сумісності) для основних бібліотек i18n (`react-i18next`, `next-intl`, `vue-i18n` тощо) та додає підтримку складних структур контенту: **Collections** (Колекцій) та **Variants** (Варіантів).
 
 ## Зміст
 
@@ -41,8 +40,10 @@ author: aymericzip
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 Наприклад, просто змініть:
 
@@ -100,7 +101,7 @@ export default defineConfig({
 
 ---
 
-## Специфікація функцій: Collections, Variants та Dynamic Records
+## Специфікація функцій: Collections та Variants
 
 Intlayer v9 виходить за рамки статичних об'єктів типу ключ-значення, дозволяючи словникам оголошувати динамічні структури макетів, які повністю типізовані від початку до кінця (end-to-end).
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Надавайте A/B тести, сезонні заголовки, feature flags або кастомні цільові сторінки (landing pages):
 
+#### Рядкові варіанти (наприклад, A/B-тестування)
+
 ```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. Динамічні записи (Dynamic Records)
-
-Визначайте словники, записи яких завантажуються динамічно під час виконання за допомогою ідентифікаторів запитів (query IDs):
+#### Об'єктні варіанти (наприклад, динамічні записи)
 
 ```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` та налаштована шлях `compiler.output`. Вам більше не потрібно реєструвати `intlayerCompiler()` окремо.
+- **Compiler**: Активується автоматично, коли `compiler.enabled` встановлено у `true` та налаштовано шлях `compiler.output`. Вам більше не потрібно реєструвати `intlayerCompiler()` окремо.
 - **Proxy**: Активується автоматично на основі нового параметра `routing.enableProxy` (`true` за замовчуванням). Він підключає middleware виявлення локалей / перенаправлення / переписування в режимі розробки, попереднього перегляду та production SSR. Вам більше не потрібно реєструвати `intlayerProxy()` окремо.
 
 ### Опція `routing.enableProxy`
@@ -252,6 +253,27 @@ export default config;
 
 ---
 
+## Компілятор вимкнено за замовчуванням
+
+Починаючи з Intlayer v9, **компілятор вимкнено за замовчуванням** (значення `compiler.enabled` тепер за замовчуванням дорівнює `false`). Щоб увімкнути вилучення ваших файлів `.content.ts` під час збірки, встановіть `compiler.enabled: true` у своїй конфігурації:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // За замовчуванням: false — потрібно для увімкнення компілятора починаючи з v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Коли компілятор вимкнено, Intlayer пропускає крок вилучення під час збірки та покладається на вже оголошені вами словники. Вмикайте його лише тоді, коли хочете, щоб плагін збирача (`@intlayer/swc`, `@intlayer/babel` або Vite-плагін `intlayer()`) вилучав вміст автоматично.
+
+---
+
 ## React Native: імпорт з одного пакета
 
 У програмі React Native або Expo вам більше не потрібно жонглювати `react-intlayer` та `react-native-intlayer`. Пакет `react-native-intlayer` тепер **реекспортує весь API `react-intlayer`** (хуки, утиліти та підшляхи `/format`, `/html` і `/markdown`), а його `IntlayerProvider` автоматично застосовує поліфіли React Native.
@@ -278,13 +300,14 @@ npm install intlayer react-native-intlayer
 
 Якщо ви оновлюєтеся з v8, зверніть увагу, що v9 не містить критичних змін (breaking changes). Проте ось ключові зміни:
 
+- **Компілятор вимкнено за замовчуванням**: значення `compiler.enabled` тепер за замовчуванням дорівнює `false`. Якщо ви покладаєтеся на вилучення ваших файлів `.content.ts` під час збірки, встановіть `compiler.enabled: true` у своєму `intlayer.config.ts`.
 - **Locales & Dialects**: Якщо ви використовуєте зовнішні залежності i18n, додайте відповідні плагіни адаптерів сумісності у вашу конфігурацію або налаштування бандлера для автоматичного перезапису імпортів.
-- **Custom Selectors**: При виклику `useIntlayer` другий параметр тепер зарезервований для об'єкта опцій, що містить `{ locale, item, variant, id }`. Якщо раніше ви передавали рядок локалі безпосередньо, ви все ще можете це робити, але для розширеного вибору рекомендується використовувати об'єкт опцій.
+- **Custom Selectors**: При виклику `useIntlayer` другий параметр тепер зарезервований для об'єкта опцій, що містить `{ locale, item, variant }`. Якщо раніше ви передавали рядок локалі безпосередньо, ви все ще можете це робити, але для розширеного вибору рекомендується використовувати об'єкт опцій.
 
 ---
 
 ## Корисні посилання
 
 - [Посібник з пакетів адаптерів сумісності (Compat Adapter Packages)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/compat/index.md)
-- [Динамічні словники - Collections, Variants та Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md)
+- [Динамічні словники - Collections та Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md)
 - [Довідник з конфігурації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)

package/docs/vi/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Từ Điển Động
-description: Tổng quan về ba tính năng từ điển động của Intlayer — bộ sưu tập, biến thể và bản ghi động — để xây dựng nội dung i18n linh hoạt, được điều khiển bằng runtime.
+updatedAt: 2026-06-26
+title: Từ điển động
+description: Tổng quan về các tính năng từ điển động của Intlayer — bộ sưu tập và biến thể — để xây dựng nội dung i18n linh hoạt, được điều khiển trong thời gian chạy.
 keywords:
-  - Từ Điển Động
-  - Bộ Sưu Tập
-  - Biến Thể
-  - Bản Ghi Động
+  - Từ điển động
+  - Bộ sưu tập
+  - Biến thể
   - Intlayer
   - Quốc tế hóa
 slugs:
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "Phát hành tính năng từ điển động"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Hợp nhất bản ghi động vào biến thể — `variant` giờ chấp nhận một chuỗi hoặc một đối tượng"
 author: aymericzip
 ---
 
-# Từ Điển Động
+# Từ điển động
 
-Intlayer hỗ trợ ba cơ chế để thể hiện nội dung vượt ra ngoài một từ điển tĩnh duy nhất cho mỗi khóa. Mỗi cơ chế được khai báo thông qua một **trường siêu dữ liệu (metadata) cấp cao nhất** trong tệp nội dung; không cần hàm bao (wrapper).
+Intlayer hỗ trợ hai cơ chế để diễn đạt nội dung vượt ra ngoài một từ điển tĩnh duy nhất cho mỗi khóa. Mỗi cơ chế được khai báo qua một **trường metadata cấp cao nhất** trong tệp nội dung; không cần hàm bao bọc.
 
-| Tính năng                                                                                                             | Trường siêu dữ liệu | Bộ chọn trong `useIntlayer` |
-| --------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------- |
-| [Bộ Sưu Tập](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/collections.md)       | `item: N`           | `{ item: N }`               |
-| [Biến Thể](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/variants.md)            | `variant: "name"`   | `{ variant: "name" }`       |
-| [Bản Ghi Động](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }`   | `{ id, … }`                 |
+| Tính năng                                                                                                       | Trường metadata                           | Bộ chọn trong `useIntlayer`                       |
+| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
+| [Bộ sưu tập](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/collections.md) | `item: N`                                 | `{ item: N }`                                     |
+| [Biến thể](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/variants.md)      | `variant: "name"` _hoặc_ `variant: { … }` | `{ variant: "name" }` _hoặc_ `{ variant: { … } }` |
 
-Cả ba cơ chế đều kết hợp với đối số ngôn ngữ (locale) và hỗ trợ tải chọn lọc / tải lười (lazy loading) thông qua `importMode`.
+Cả hai đều kết hợp với đối số locale và hỗ trợ tải chọn lọc / lười qua `importMode`.
 
-## Khi nào nên sử dụng tính năng nào
+## Khi nào dùng cái nào
 
-- **Bộ sưu tập** — danh sách các mục có thứ tự được quản lý trong các tệp riêng biệt (mục FAQ, bài viết blog, sản phẩm).
-- **Biến thể** — các lựa chọn nội dung thay thế được đặt tên cho các thử nghiệm A/B, biểu ngữ theo mùa hoặc cờ tính năng (feature flags).
-- **Bản ghi động** — nội dung được truy xuất tại runtime bằng một ID ẩn (bản ghi CMS, nội dung dành riêng cho người dùng).
+- **Bộ sưu tập** — danh sách mục được sắp xếp, quản lý trong các tệp riêng (mục FAQ, bài blog, sản phẩm).
+- **Biến thể** — các lựa chọn nội dung được đặt tên hoặc có cấu trúc:
+  - biến thể **chuỗi** cho thử nghiệm A/B, banner theo mùa hoặc feature flag;
+  - biến thể **đối tượng** cho bản ghi CMS, nội dung riêng theo người dùng, hoặc bất kỳ nội dung nào được định địa chỉ bằng một tập hợp trường ("bản ghi động" trước đây).
 
-## Giải quyết xung đột bộ chọn
+> Các phiên bản trước cung cấp một trường `meta` riêng cho nội dung được khóa theo bản ghi. Nó đã được hợp nhất vào `variant`: hãy truyền một **đối tượng** cho `variant` thay vì dùng `meta`.
 
-Khi có nhiều bộ chọn tồn tại trên cùng một từ điển, thứ tự ưu tiên giải quyết là:
+## Khử nhập nhằng bộ chọn
+
+Một khóa có thể khai báo cả hai chiều cùng lúc (ví dụ một bộ sưu tập mà mỗi mục có một biến thể). Chúng được phân giải theo thứ tự:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+Vì vậy, `{ variant: "promo" }` trên khóa variant × item trả về mọi mục promo dưới dạng mảng, và thêm `{ item: 2 }` thu hẹp lại còn một mục duy nhất.