@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

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:
@@ -15,19 +17,29 @@ slugs:
   - concept
   - variants
 history:
-  - version: 8.13.0
+  - 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/formatters.md

@@ -116,10 +116,6 @@ pluralRules.select(1); // "one"
 pluralRules.select(2); // "інше"
 ```
 
-## Додаткові утиліти Intl
-
-Окрім допоміжних форматерів, ви також можете безпосередньо використовувати кешований обгорток Intl для інших можливостей Intl:
-
 ### `Intl.DisplayNames`
 
 Для локалізованих назв мов, регіонів, валют та писемностей:
@@ -182,20 +178,6 @@ getLocaleName("de", "es"); // іспанською: "alemán"
 - **displayLocale**: Локаль, для якої потрібно отримати назву
 - **targetLocale**: Локаль, в якій відображається назва (за замовчуванням displayLocale)
 
-### `getLocaleLang(locale?)`
-
-Витягує код мови з рядка локалі:
-
-```ts
-import { getLocaleLang } from "intlayer";
-
-getLocaleLang("en-US"); // "en"
-getLocaleLang("fr-CA"); // "fr"
-getLocaleLang("de"); // "de"
-```
-
-- **locale**: Локаль, з якої потрібно витягти код мови (за замовчуванням поточна локаль)
-
 ### `getLocaleFromPath(inputUrl)`
 
 Витягує сегмент локалі з URL або шляху:
@@ -212,22 +194,6 @@ getLocaleFromPath("https://example.com/es/about"); // "es"
 - **inputUrl**: Повний рядок URL або шлях (pathname) для обробки
 - **returns**: Виявлена локаль або локаль за замовчуванням, якщо локаль не знайдена
 
-### `getPathWithoutLocale(inputUrl, locales?)`
-
-Видаляє сегмент локалі з URL або шляху (pathname):
-
-```ts
-import { getPathWithoutLocale } from "intlayer";
-
-getPathWithoutLocale("/en/dashboard"); // "/dashboard"
-getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
-getPathWithoutLocale("https://example.com/en/about"); // "https://example.com/about"
-```
-
-- **inputUrl**: Повний рядок URL або шлях (pathname) для обробки
-- **locales**: Необов'язковий масив підтримуваних локалей (за замовчуванням використовується сконфігурований список локалей)
-- **returns**: URL без сегменту локалі
-
 ### `getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)`
 
 Генерує локалізований URL для поточної локалі:
@@ -261,8 +227,6 @@ getHTMLTextDir("he"); // повертає "rtl"
 - **locale**: Локаль, для якої потрібно отримати напрямок тексту (за замовчуванням, поточна локаль)
 - **повертає**: `"ltr"`, `"rtl"`, або `"auto"`
 
-## Утиліти обробки контенту
-
 ### `getContent(node, nodeProps, locale?)`
 
 Перетворює вузол контенту за допомогою всіх доступних плагінів (translation, enumeration, insertion тощо):
@@ -281,28 +245,6 @@ const content = getContent(
 - **nodeProps**: Властивості для контексту перетворення
 - **locale**: Необов'язкова локаль (за замовчуванням використовується налаштована локаль)
 
-### `getTranslation(languageContent, locale?, fallback?)`
-
-Витягує вміст для конкретної локалі з об'єкта мовного вмісту:
-
-```ts
-import { getTranslation } from "intlayer";
-
-const content = getTranslation(
-  {
-    en: "Hello",
-    fr: "Bonjour",
-    de: "Hallo",
-  },
-  "fr",
-  true
-); // "Bonjour"
-```
-
-- **languageContent**: Об'єкт, що відображає локалі на відповідний вміст
-- **locale**: Цільова локаль (за замовчуванням використовується налаштована локаль)
-- **fallback**: Чи виконувати відкат до локалі за замовчуванням (за замовчуванням true)
-
 ### `getIntlayer(dictionaryKey, locale?, plugins?)`
 
 Отримує та трансформує вміст із словника за ключем:
@@ -468,12 +410,87 @@ list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge
 list([1, 2, 3], { type: "unit" }); // "1, 2, 3"
 ```
 
+## Cached Intl
+
+Експортований `Intl` з `intlayer` — це кешований wrapper навколо глобального `Intl`. Він мемоізує екземпляри форматерів (`NumberFormat`, `DateTimeFormat` тощо), щоб уникнути їхнього повторного створення та поліпшити продуктивність.
+
+```ts
+import { Intl } from "intlayer";
+
+// Форматування чисел
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+
+// Назви відображення для мов, регіонів тощо
+const displayNames = new Intl.DisplayNames("fr", { type: "language" });
+displayNames.of("en"); // "anglais"
+
+// Collation для сортування
+const collator = new Intl.Collator("fr", { sensitivity: "base" });
+collator.compare("é", "e"); // 0 (equal)
+
+// Правила множини
+const pluralRules = new Intl.PluralRules("fr");
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "other"
+```
+
+### Додаткові функції Intl
+
 ## Примітки
 
 - Усі утиліти приймають вхідні значення як `string`; всередині вони приводяться до чисел або дат.
 - Якщо локаль не вказана, за замовчуванням використовується налаштована вами `internationalization.defaultLocale`.
 - Ці утиліти, тонкі обгортки; для просунутого форматування передавайте стандартні опції `Intl`.
 
+#### `Intl.Collator`
+
+Для локалізованого порівняння та сортування рядків:
+
+```ts
+import { Intl } from "intlayer";
+
+const collator = new Intl.Collator("de", {
+  sensitivity: "base",
+  numeric: true,
+});
+
+const words = ["äpfel", "zebra", "100", "20"];
+words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]
+```
+
+#### `Intl.PluralRules`
+
+Для визначення форм множини в різних локалях:
+
+```ts
+import { Intl } from "intlayer";
+
+const pluralRules = new Intl.PluralRules("ar");
+pluralRules.select(0); // "zero"
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "two"
+pluralRules.select(3); // "few"
+pluralRules.select(11); // "many"
+```
+
+## Locale Utilities
+
+### `getLocaleName(displayLocale, targetLocale?)`
+
+Отримує локалізовану назву локалі:
+
+```ts
+import { getLocaleName } from "intlayer";
+
+getLocaleName("fr", "en"); // "French"
+getLocaleName("en", "fr"); // "anglais"
+getLocaleName("de", "es"); // "alemán"
+```
+
 ## Точки входу та повторні експорти (`@index.ts`)
 
 Форматери містяться в core-пакеті і реекспортуються з пакетів вищого рівня, щоб зробити імпорти зручними в різних середовищах виконання:
@@ -503,6 +520,29 @@ import {
 } from "intlayer";
 ```
 
+### `getLocaleFromPath(inputUrl)`
+
+Витягує сегмент локалі з URL-адреси або шляху:
+
+```ts
+import { getLocaleFromPath } from "intlayer";
+
+getLocaleFromPath("/en/dashboard"); // "en"
+getLocaleFromPath("/fr/dashboard"); // "fr"
+getLocaleFromPath("/dashboard"); // "en" (локаль за замовчуванням)
+```
+
+### `getPathWithoutLocale(inputUrl, locales?)`
+
+Видаляє сегмент локалі з URL:
+
+```ts
+import { getPathWithoutLocale } from "intlayer";
+
+getPathWithoutLocale("/en/dashboard"); // "/dashboard"
+getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
+```
+
 ### React
 
 Клієнтські компоненти:
@@ -576,6 +616,20 @@ import {
 
 > Ці хуки братимуть до уваги локаль із `IntlayerProvider` або `IntlayerServerProvider`
 
+### `getHTMLTextDir(locale?)`
+
+Повертає напрямок тексту для локалі:
+
+```ts
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir("en-US"); // "ltr"
+getHTMLTextDir("ar"); // "rtl"
+getHTMLTextDir("he"); // "rtl"
+```
+
+## Утиліти обробки вмісту
+
 ### Vue
 
 Клієнтські компоненти:
@@ -594,3 +648,33 @@ import {
 ```
 
 > Ці composables братимуть до уваги локаль із ін'єктованого `IntlayerProvider`
+
+### `getTranslation(languageContent, locale?, fallback?)`
+
+Витягує вміст для конкретної локалі:
+
+```ts
+import { getTranslation } from "intlayer";
+
+const content = getTranslation(
+  { en: "Hello", fr: "Bonjour", de: "Hallo" },
+  "fr",
+  true
+); // "Bonjour"
+```
+
+### `getIntlayer(dictionaryKey, locale?, plugins?)`
+
+Отримує та трансформує вміст зі словника:
+
+```ts
+import { getIntlayer } from "intlayer";
+
+const content = getIntlayer("common", "fr");
+```
+
+## Примітки
+
+- Усі помічники приймають входи типу `string`; внутрішньо вони перетворюються на числа або дати.
+- Locale за замовчуванням використовує ваш налаштований `internationalization.defaultLocale`, якщо він не надано.
+- Ці утиліти є тонкими обгортками; для розширеного форматування передайте стандартні параметри `Intl`.