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

package/docs/ru/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: "ru",
+  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/ru/bundle_optimization.md) для подробностей о режимах `static`, `dynamic` и `fetch`.
+
+## Типичные сценарии использования
 
-- A/B-тестирование текстов, управляемое ключом эксперимента
-- Сезонные или промо-баннеры
-- Сообщения, управляемые флагами функций (feature flags)
-- Маркетинговые кампании для конкретных регионов
+- A/B-тесты текста, управляемые ключом эксперимента
+- Сезонные или рекламные баннеры
+- Сообщения под feature-флагами
+- Маркетинговые кампании для конкретной локали
+- Маркетинговый текст по товарам, управляемый в CMS
+- Контент конкретного пользователя или аккаунта
+- Любой контент, адресуемый непрозрачным ID во время выполнения

package/docs/ru/formatters.md

@@ -176,6 +176,100 @@ getLocaleName("de", "es"); // "alemán"
 - **displayLocale**: Локаль, для которой нужно получить название
 - **targetLocale**: Локаль, на которой будет отображаться название (по умолчанию displayLocale)
 
+### Доступные Composables
+
+Все composables возвращают computed refs, которые автоматически используют локаль из внедренного `IntlayerProvider`.
+
+| Composable          | Описание                                    | Пример вывода                 |
+| ------------------- | ------------------------------------------- | ----------------------------- |
+| `useNumber()`       | Форматирование чисел с группировкой         | `"123,456.789"`               |
+| `useCurrency()`     | Форматирование значений валют               | `"€1,234.50"`                 |
+| `usePercentage()`   | Форматирование процентов                    | `"25%"`                       |
+| `useDate()`         | Форматирование дат и времени                | `"Aug 2, 2025"`               |
+| `useRelativeTime()` | Форматирование относительного времени       | `"in 3 days"`                 |
+| `useUnit()`         | Форматирование значений с единицами         | `"5 kilometers"`              |
+| `useCompact()`      | Форматирование чисел в компактной нотации   | `"1.2K"`                      |
+| `useList()`         | Форматирование массивов как списки          | `"apple, banana, and orange"` |
+| `useIntl()`         | Получить привязанный к локали объект `Intl` | Полный доступ к `Intl` API    |
+
+### Полный пример
+
+```vue
+<script setup>
+import {
+  useNumber,
+  useCurrency,
+  useDate,
+  usePercentage,
+  useCompact,
+  useList,
+  useRelativeTime,
+  useUnit,
+} from "vue-intlayer/format";
+
+const number = useNumber();
+const currency = useCurrency();
+const date = useDate();
+const percentage = usePercentage();
+const compact = useCompact();
+const list = useList();
+const relativeTime = useRelativeTime();
+const unit = useUnit();
+</script>
+
+<template>
+  <div>
+    <p>{{ number.value(123456.789) }}</p>
+    <p>{{ currency.value(1234.5, { currency: "EUR" }) }}</p>
+    <p>{{ date.value(new Date(), "short") }}</p>
+    <p>{{ percentage.value(0.25) }}</p>
+    <p>{{ compact.value(1200) }}</p>
+    <p>{{ list.value(["apple", "banana", "orange"]) }}</p>
+    <p>{{ relativeTime.value(new Date(), new Date(Date.now() + 86400000)) }}</p>
+    <p>{{ unit.value(5, { unit: "kilometer" }) }}</p>
+  </div>
+</template>
+```
+
+### Composable `useIntl`
+
+Composable `useIntl` предоставляет прямой доступ к объекту `Intl`, привязанному к локали. Это полезно, когда вам нужен полный API `Intl` с автоматическим внедрением локали.
+
+```vue
+<script setup>
+import { useIntl } from "vue-intlayer/format";
+
+const intl = useIntl(); // использует локаль контекста
+
+// Стандартный API Intl, но локаль автоматически внедряется, если не определена
+const formatted = new intl.value.NumberFormat(undefined, {
+  style: "currency",
+  currency: "USD",
+}).format(123.45);
+
+// Вы все еще можете переопределить локаль, если необходимо
+const date = new intl.value.DateTimeFormat("fr-FR").format(new Date());
+
+// Доступ к другим функциям Intl
+const displayNames = new intl.value.DisplayNames(undefined, {
+  type: "language",
+});
+const languageName = displayNames.of("fr");
+</script>
+
+<template>
+  <div>
+    <p>{{ formatted }}</p>
+    <p>{{ date }}</p>
+    <p>{{ languageName }}</p>
+  </div>
+</template>
+```
+
+## Vanilla JS / Node.js Formatters
+
+Для контекстов без framework'а импортируйте форматтеры напрямую из `intlayer`. Обратите внимание, что вы должны передать locale вручную.
+
 ### `getLocaleLang(locale?)`
 
 Извлекает код языка из строки локали:
@@ -190,6 +284,8 @@ getLocaleLang("de"); // "de"
 
 - **locale**: Локаль, из которой нужно извлечь язык (по умолчанию текущая локаль)
 
+### Функции форматирования
+
 ### `getLocaleFromPath(inputUrl)`
 
 Извлекает сегмент локали из URL или пути:
@@ -312,6 +408,36 @@ const nestedContent = getIntlayer("common", "fr", customPlugins);
 - **locale**: Необязательная локаль (по умолчанию используется настроенная локаль по умолчанию)
 - **plugins**: Необязательный массив пользовательских плагинов трансформации
 
+## Cached Intl
+
+Экспортируемый `Intl` из `intlayer` — это кэшированная обёртка вокруг глобального `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"
+
+// Сортировка по правилам коллации
+const collator = new Intl.Collator("fr", { sensitivity: "base" });
+collator.compare("é", "e"); // 0 (equal)
+
+// Правила plurals
+const pluralRules = new Intl.PluralRules("fr");
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "other"
+```
+
+### Дополнительные возможности Intl
+
 ### `getIntlayerAsync(dictionaryKey, locale?, plugins?)`
 
 Асинхронно получает контент из удалённого словаря:
@@ -347,6 +473,8 @@ number("1000000", { locale: "fr" }); // "1 000 000"
 number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
 ```
 
+## Утилиты Локализации
+
 ### `percentage(value, options?)`
 
 Форматирует число в строку с процентами.
@@ -457,6 +585,8 @@ compact(1200); // "1.2K"
 compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
 ```
 
+## Утилиты для обработки содержимого
+
 ### `list(values, options?)`
 
 Форматирует массив значений в локализованную строку списка с использованием `Intl.ListFormat`.
@@ -591,3 +721,9 @@ import {
 ```
 
 > Эти композиционные функции будут учитывать локаль из внедренного `IntlayerProvider`
+
+## Примечания
+
+- Все вспомогательные функции принимают входные данные типа `string`; они внутренне преобразуются в числа или даты.
+- Локаль по умолчанию использует ваш настроенный `internationalization.defaultLocale`, если не указана.
+- Эти утилиты являются тонкими оболочками; для продвинутого форматирования передавайте стандартные параметры `Intl`.

package/docs/ru/how_works_intlayer.md

@@ -22,6 +22,10 @@ author: aymericzip
 
 # Как работает Intlayer
 
+## Таблица содержания
+
+<TOC/>
+
 ## Обзор
 
 Основная идея Intlayer заключается в использовании управления контентом на уровне компонентов. Идея Intlayer состоит в том, чтобы позволить вам объявлять ваш контент в любом месте вашего кода, например, в той же директории, что и ваш компонент.

package/docs/ru/intlayer_CMS.md

@@ -40,6 +40,12 @@ Intlayer CMS, это приложение, которое позволяет в
 
 ![Интерфейс Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/assets/CMS.png)
 
+## Оглавление
+
+<TOC/>
+
+---
+
 ## Понимание удалённых словарей
 
 Intlayer различает «локальные» и «удалённые» словари.

package/docs/ru/intlayer_with_adonisjs.md

@@ -59,24 +59,40 @@ See [Application Template](https://github.com/aymericzip/intlayer-adonis-templat
 
 Чтобы начать использовать `adonis-intlayer`, установите пакет с помощью npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```bash packageManager="npm"
 npm install intlayer adonis-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer adonis-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer adonis-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer adonis-intlayer
-bun x intlayer init
 ```
 
 ### Настройка

package/docs/ru/intlayer_with_analog.md

@@ -118,24 +118,40 @@ Intlayer — это больше, чем просто решение i18n. Он
 
 Установите необходимые пакеты с помощью npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```bash packageManager="npm"
 npm install intlayer angular-intlayer vite-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer angular-intlayer vite-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer angular-intlayer vite-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer angular-intlayer vite-intlayer
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -191,7 +207,11 @@ import analog from "@analogjs/platform";
 export default defineConfig(() => ({
   plugins: [
     analog(),
-    intlayer(), // Добавьте плагин Intlayer
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 }));
 ```