@intlayer/docs 8.12.4-canary.0 → 8.12.5-canary.0

package/docs/ru/dictionary/nesting.md

@@ -16,6 +16,7 @@ slugs:
   - concept
   - content
   - nesting
+author: aymericzip
 ---
 
 # Вложенность / Ссылки на Подконтент

package/docs/ru/dictionary/plurial.md

@@ -22,6 +22,7 @@ history:
   - version: 8.8.0
     date: 2026-05-04
     changes: "Init history"
+author: aymericzip
 ---
 
 # Контент во множественном числе / Множественное число в Intlayer

package/docs/ru/dictionary/translation.md

@@ -20,6 +20,7 @@ history:
   - version: 5.5.10
     date: 2025-06-29
     changes: "Инициализация истории"
+author: aymericzip
 ---
 
 # Перевод

package/docs/ru/dynamic_dictionaries/collections.md

@@ -0,0 +1,246 @@
+---
+createdAt: 2026-06-12
+updatedAt: 2026-06-12
+title: Коллекции
+description: Используйте поле метаданных item в файлах контента Intlayer для создания упорядоченных коллекций локализованных элементов, выбираемых по индексу во время выполнения.
+keywords:
+  - Коллекции
+  - Список Контента
+  - Динамический Контент
+  - Intlayer
+  - Интернационализация
+slugs:
+  - doc
+  - concept
+  - collections
+history:
+  - version: 8.13.0
+    date: 2026-06-12
+    changes: "Выпуск функции словарей коллекций"
+author: aymericzip
+---
+
+# Коллекции
+
+**Коллекция** (Collection) — это набор файлов контента, которые используют один и тот же ключ словаря (`key`), но каждый объявляет свой индекс элемента `item`. Intlayer объединяет их в единый упорядоченный список во время сборки.
+
+## Объявление элементов коллекции
+
+Каждый файл представляет собой один элемент. Поле `item` указывает на его позицию в списке (начиная с 1).
+
+```ts fileName="faq.1.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "faq",
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+```ts fileName="faq.2.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+## Использование коллекции
+
+### Все элементы
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="FAQ.tsx"
+    import { useIntlayer } from "react-intlayer";
+
+    export const FAQ = () => {
+      const items = useIntlayer("faq"); // { question: string; answer: string }[]
+
+      return (
+        <ul>
+          {items.map((item, index) => (
+            <li key={index}>
+              <strong>{item.question}</strong>
+              <p>{item.answer}</p>
+            </li>
+          ))}
+        </ul>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="FAQ.tsx"
+    import { useIntlayer } from "next-intlayer";
+
+    export const FAQ = () => {
+      const items = useIntlayer("faq"); // { question: string; answer: string }[]
+
+      return (
+        <ul>
+          {items.map((item, index) => (
+            <li key={index}>
+              <strong>{item.question}</strong>
+              <p>{item.answer}</p>
+            </li>
+          ))}
+        </ul>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```vue fileName="FAQ.vue"
+    <script setup>
+    import { useIntlayer } from "vue-intlayer";
+    const items = useIntlayer("faq");
+    </script>
+
+    <template>
+      <ul>
+        <li v-for="(item, index) in items" :key="index">
+          <strong>{{ item.question }}</strong>
+          <p>{{ item.answer }}</p>
+        </li>
+      </ul>
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="FAQ.svelte"
+    <script lang="ts">
+    import { useIntlayer } from "svelte-intlayer";
+    const items = useIntlayer("faq");
+    </script>
+
+    <ul>
+      {#each $items as item}
+        <li>
+          <strong>{item.question}</strong>
+          <p>{item.answer}</p>
+        </li>
+      {/each}
+    </ul>
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="FAQ.tsx"
+    import { useIntlayer } from "preact-intlayer";
+
+    export const FAQ = () => {
+      const items = useIntlayer("faq"); // { question: string; answer: string }[]
+
+      return (
+        <ul>
+          {items.map((item, index) => (
+            <li key={index}>
+              <strong>{item.question}</strong>
+              <p>{item.answer}</p>
+            </li>
+          ))}
+        </ul>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="FAQ.tsx"
+    import { useIntlayer } from "solid-intlayer";
+    import { For } from "solid-js";
+
+    export const FAQ = () => {
+      const items = useIntlayer("faq"); // { question: string; answer: string }[]
+
+      return (
+        <ul>
+          <For each={items()}>
+            {(item) => (
+              <li>
+                <strong>{item.question}</strong>
+                <p>{item.answer}</p>
+              </li>
+            )}
+          </For>
+        </ul>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="faq.component.ts"
+    import { Component } from "@angular/core";
+    import { useIntlayer } from "angular-intlayer";
+
+    @Component({
+      selector: "app-faq",
+      template: `
+        <ul>
+          @for (item of items(); track $index) {
+            <li>
+              <strong>{{ item.question }}</strong>
+              <p>{{ item.answer }}</p>
+            </li>
+          }
+        </ul>
+      `,
+    })
+    export class FAQComponent {
+      items = useIntlayer("faq");
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="faq.js"
+    import { useIntlayer } from "vanilla-intlayer";
+
+    const faq = useIntlayer("faq");
+
+    faq.forEach((item) => {
+      console.log(item.question);
+      console.log(item.answer);
+    });
+    ```
+
+  </Tab>
+</Tabs>
+
+### Один элемент по индексу
+
+```tsx
+const faq2 = useIntlayer("faq", { item: 2 });
+// → { question: string; answer: string }
+```
+
+### Один элемент с явным указанием локали
+
+```tsx
+const faq2Ru = useIntlayer("faq", { item: 2, locale: "ru" });
+```
+
+## Типичные варианты использования
+
+- Списки FAQ (Часто задаваемые вопросы)
+- Тарифные сетки / ценовые планы
+- Слайды каруселей / слайдеров
+- Пошаговые инструкции

package/docs/ru/dynamic_dictionaries/dynamic_content.md

@@ -0,0 +1,271 @@
+---
+createdAt: 2026-06-12
+updatedAt: 2026-06-12
+title: Динамические Записи
+description: Используйте поле meta в файлах контента Intlayer для объявления записей, управляемых CMS, получаемых во время выполнения по непрозрачному идентификатору ID, что обеспечивает строгую типизацию динамического контента без перечисления во время сборки.
+keywords:
+  - Динамические Записи
+  - Динамический Контент
+  - CMS
+  - Контент во Время Выполнения
+  - Intlayer
+  - Интернационализация
+slugs:
+  - doc
+  - concept
+  - dynamic-records
+history:
+  - version: 8.13.0
+    date: 2026-06-12
+    changes: "Выпуск функции динамического контента"
+author: aymericzip
+---
+
+# Динамические Записи
+
+**Динамическая запись** (dynamic record) — это файл контента, идентификация которого основана не на последовательном индексе или именованном варианте, а на произвольном наборе пар ключ-значение, объявленных в поле `meta`. Intlayer использует эти поля в качестве селектора во время выполнения, что позволяет адресовать записи CMS, контент конкретного пользователя или любые данные, ключи которых неизвестны во время сборки.
+
+## Объявление динамических записей
+
+```ts fileName="product-copy.abc.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "product-copy",
+  meta: {
+    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-copy.abcd.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const dictionary = {
+  key: "product-copy",
+  meta: {
+    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;
+```
+
+## Использование динамических записей
+
+Все поля `meta` являются **обязательными** в селекторе. Опущение любого поля возвращает `null` и вызывает ошибку TypeScript.
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+    ```tsx fileName="ProductCopy.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "react-intlayer";
+
+    export const ProductCopy = ({
+      productId,
+      userId,
+    }: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product-copy", { id: productId, userId });
+      // TypeScript гарантирует, что предоставлены как `id`, так и `userId`.
+
+      if (!content) return null;
+
+      return <p>{content.description}</p>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    ```tsx fileName="ProductCopy.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "next-intlayer";
+
+    export const ProductCopy = ({
+      productId,
+      userId,
+    }: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product-copy", { id: productId, userId });
+      // TypeScript гарантирует, что предоставлены как `id`, так и `userId`.
+
+      if (!content) return null;
+
+      return <p>{content.description}</p>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+    ```vue fileName="ProductCopy.vue" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    <script setup>
+    import { useIntlayer } from "vue-intlayer";
+
+    const props = defineProps({
+      productId: String,
+      userId: String,
+    });
+
+    const content = useIntlayer("product-copy", { id: props.productId, userId: props.userId });
+    </script>
+
+    <template>
+      <p v-if="content">{{ content.description }}</p>
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    ```svelte fileName="ProductCopy.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-copy", { id: productId, userId });
+    </script>
+
+    {#if $content}
+      <p>{$content.description}</p>
+    {/if}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    ```tsx fileName="ProductCopy.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "preact-intlayer";
+
+    export const ProductCopy = ({
+      productId,
+      userId,
+    }: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product-copy", { id: productId, userId });
+      // TypeScript гарантирует, что предоставлены как `id`, так и `userId`.
+
+      if (!content) return null;
+
+      return <p>{content.description}</p>;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    ```tsx fileName="ProductCopy.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { useIntlayer } from "solid-intlayer";
+
+    export const ProductCopy = (props: {
+      productId: string;
+      userId: string;
+    }) => {
+      const content = useIntlayer("product-copy", { id: props.productId, userId: props.userId });
+      // TypeScript гарантирует, что предоставлены как `id`, так и `userId`.
+
+      return (
+        <>
+          {content() && <p>{content().description}</p>}
+        </>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    ```typescript fileName="product-copy.component.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+    import { Component, Input, OnInit } from "@angular/core";
+    import { useIntlayer } from "angular-intlayer";
+
+    @Component({
+      selector: "app-product-copy",
+      template: `
+        @if (content()) {
+          <p>{{ content().description }}</p>
+        }
+      `,
+    })
+    export class ProductCopyComponent implements OnInit {
+      @Input() productId!: string;
+      @Input() userId!: string;
+
+      content: any;
+
+      ngOnInit() {
+        this.content = useIntlayer("product-copy", { id: this.productId, userId: this.userId });
+      }
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+    ```javascript fileName="product-copy.js"
+    import { useIntlayer } from "vanilla-intlayer";
+
+    const content = useIntlayer("product-copy", {
+      id: "prod_abcd",
+      userId: "user_123"
+    });
+
+    if (content) {
+      document.body.innerHTML = `<p>${content.description}</p>`;
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+### С явным указанием локали
+
+```tsx
+const content = useIntlayer("product-copy", {
+  id: "prod_abc",
+  userId: "user_123",
+  locale: "ru",
+});
+```
+
+### Отсутствие поля meta — ошибка во время компиляции
+
+```ts
+// Ошибка типа: отсутствует `userId`
+const content = useIntlayer("product-copy", { id: "prod_abc" });
+```
+
+## Режим загрузки (loading mode)
+
+Динамические записи обычно загружаются отложено. Установите `importMode` для словаря, чтобы настроить это:
+
+```ts contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+const dictionary = {
+  key: "product-copy",
+  importMode: "fetch", // или "dynamic"
+  meta: { id: "prod_abc", userId: "user_123" },
+  content: { … },
+} satisfies Dictionary;
+
+export default dictionary;
+```
+
+Подробную информацию о режимах `static`, `dynamic` и `fetch` см. в разделе [оптимизация пакетов](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/bundle_optimization.md).
+
+## Типичные варианты использования
+
+- Маркетинговые тексты для отдельных продуктов, управляемые в CMS
+- Контент конкретного пользователя или учетной записи
+- Любой контент, получаемый на основе непрозрачного runtime ID

package/docs/ru/dynamic_dictionaries/index.md

@@ -0,0 +1,48 @@
+---
+createdAt: 2026-06-12
+updatedAt: 2026-06-12
+title: Динамические Словари
+description: Обзор трех функций динамических словарей Intlayer — коллекций, вариантов и динамических записей — для создания гибкого контента i18n, управляемого во время выполнения.
+keywords:
+  - Динамические Словари
+  - Коллекции
+  - Варианты
+  - Динамические Записи
+  - Intlayer
+  - Интернационализация
+slugs:
+  - doc
+  - concept
+  - dynamic-dictionaries
+history:
+  - version: 8.13.0
+    date: 2026-06-12
+    changes: "Выпуск функции динамических словарей"
+author: aymericzip
+---
+
+# Динамические Словари
+
+Intlayer поддерживает три механизма для представления контента, выходящего за рамки одного статического словаря на ключ. Каждый из них объявляется через **поле метаданных верхнего уровня** в файле контента; функция-обертка (wrapper) не требуется.
+
+| Функция                                                                                                                      | Поле метаданных   | Селектор в `useIntlayer` |
+| ---------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------ |
+| [Коллекции](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/collections.md)               | `item: N`         | `{ item: N }`            |
+| [Варианты](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/variants.md)                   | `variant: "name"` | `{ variant: "name" }`    |
+| [Динамические Записи](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`              |
+
+Все три механизма сочетаются с аргументом локали и поддерживают выборочную / ленивую загрузку (lazy loading) с помощью `importMode`.
+
+## Когда что использовать
+
+- **Коллекции** — упорядоченный список элементов, управляемых в отдельных файлах (элементы FAQ, сообщения в блогах, продукты).
+- **Варианты** — именованные альтернативы контента для A/B-тестов, сезонных баннеров или флагов функций (feature flags).
+- **Динамические записи** — контент, получаемый во время выполнения по непрозрачному идентификатору ID (записи CMS, контент конкретного пользователя).
+
+## Разрешение конфликтов селекторов
+
+Когда в словаре присутствует несколько селекторов, порядок разрешения следующий:
+
+```
+variant → meta → item
+```