@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/ru/packages/intlayer/getDictionary.md

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Документация функции getDictionary | intlayer
+description: Узнайте, как использовать функцию getDictionary в пакете intlayer
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Документация: функция `getDictionary` в `intlayer`
+
+## Описание
+
+Функция `getDictionary` интерпретирует словарь **объект, который вы передаёте сами**, и возвращает его разрешённое содержимое для заданной локали. Она проходит содержимое в один проход и применяет каждый плагин интерпретатора по мере необходимости, разрешая переводы `t()`, перечисления, условия, вставки, вложенность, markdown, HTML и узлы файлов.
+
+В отличие от [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getIntlayer.md), которая ищет словарь по ключу в сгенерированном реестре, `getDictionary` принимает сам словарь. Это делает её правильным инструментом для содержимого, построенного во время выполнения, полученного из API или CMS, или объявленного встроенно в тесте.
+
+**Ключевые особенности:**
+
+- Работает с любым объектом, следующим структуре словаря (`{ key, content }`)
+- Также принимает квалифицированную группу словаря (коллекции, варианты) вместе с селектором
+- Полностью типизирована: возвращаемый объект отражает `content`, который вы передали
+- Принимает пользовательские плагины интерпретатора
+
+---
+
+## Сигнатура функции
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Обязательно
+  localeOrSelector?: LocalesValues | DictionarySelector, // Опционально
+  plugins?: Plugins[]                                // Опционально
+): DeepTransformContent<...>
+```
+
+---
+
+## Параметры
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Description**: Словарь (или квалифицированная группа словарей) для интерпретации.
+  - **Type**: `Dictionary | QualifiedDictionaryGroup`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Локаль для интерпретации содержимого или объект селектора (`{ item }`, `{ variant }`, опционально с `locale`). См. [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Массив преобразователей узлов, определяющих способ интерпретации распознанных узлов. Если не указано, используется набор плагинов интерпретатора по умолчанию.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Возвращаемое значение
+
+- **Type**: The interpreted content of the dictionary.
+- **Description**: The `content` you passed, with every Intlayer node resolved for the requested locale. For a collection group without an `item` selector, an ordered array of interpreted entries is returned; `null` is returned when the selector targets nothing.
+
+---
+
+## Пример использования
+
+### Базовое использование
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        ru: "Привет",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "ru"
+);
+
+console.log(content.greeting); // "Привет"
+```
+
+### Интерпретация контента, полученного во время выполнения
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### С селектором
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Квалифицированная группа словаря разрешается в одну запись…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …или в упорядоченный массив, если `item` не указан
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Связанные функции
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getIntlayer.md): Аналогичная интерпретация, но словарь ищется по ключу в созданном реестре.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getDictionaryAsync.md): Аналог для карт загрузчиков для каждой локали.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/react-intlayer/useDictionary.md): Эквивалент React хука, читающий локаль от провайдера.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/ru/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Документация функции getDictionaryAsync | intlayer
+description: Узнайте, как использовать функцию getDictionaryAsync для пакета intlayer
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Документация: Функция `getDictionaryAsync` в `intlayer`
+
+## Описание
+
+Функция `getDictionaryAsync` загружает **единый языковой chunk** словаря и возвращает его интерпретированное содержимое.
+
+Это аналог [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getDictionary.md) для maps загрузчиков для отдельных языков, выпускаемых в `.intlayer/dynamic_dictionaries/`: вместо получения словаря со всеми языками он получает map загрузчика и ожидает только chunk для запрошенного языка.
+
+> В коде приложения вы обычно вызываете [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getIntlayerAsync.md), а не эту функцию. [Плагины сборки](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/bundle_optimization.md) переписывают каждый вызов `getIntlayerAsync('key', locale)` на `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` экспортируется для пользовательских загрузчиков и для инструментов, которые создают свои собственные maps загрузчиков.
+
+**Ключевые особенности:**
+
+- Загружает только запрошенный языковой chunk
+- Поддерживает простые (`locale → loader`) и квалифицированные (`locale → qualifierId → loader`) maps загрузчиков
+- Дедублирует одновременные загрузки одного chunk и кэширует разрешенное содержимое
+- Неудачные загрузки удаляются из кэша, поэтому последующий вызов повторит попытку загрузки chunk
+
+---
+
+## Сигнатура функции
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Обязательно
+  key: string,                                           // Обязательно
+  localeOrSelector?: LocalesValues | DictionarySelector, // Опционально
+  plugins?: Plugins[]                                    // Опционально
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Параметры
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: Карта загрузчиков для каждой локали. Простые карты связывают локаль с загрузчиком; квалифицированные карты (используются коллекциями и вариантами) связывают локаль с идентификатором квалификатора, затем с загрузчиком. Для квалифицированной карты загружаются только фрагменты, на которые указывает селектор.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: Ключ словаря, используется для разделения кэша фрагментов.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Локаль для интерпретации контента или объект селектора (`{ item }`, `{ variant }`, опционально с `locale`). См. [динамические словари](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — по умолчанию используется настроенная `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Node трансформеры. По умолчанию используется базовый набор интерпретатора.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — a promise resolving to the interpreted content of the loaded chunk.
+- **Description**: Resolves to `null` when the map emits no chunk for the requested locale nor for any of its fallbacks, mirroring how a missing qualified coordinate resolves.
+
+---
+
+## Пример использования
+
+### С генерируемой картой загрузчика
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### С пользовательской картой загрузчика
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### С селектором на квалифицированной карте
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Примечания о поведении
+
+### Кеширование и дедупликация
+
+Кеш сохраняет **promise** каждой тройки `key + locale + selector`, поэтому одновременные вызовы для одного chunk ждут одной загрузки. Отклоненная загрузка удаляется из кеша, поэтому неудавшийся chunk повторяется при следующем вызове вместо того, чтобы воспроизводить одну и ту же ошибку бесконечно.
+
+### Fallback локали
+
+Простая карта загрузчика следует той же цепочке fallback, что и синхронный режим: сначала запрашиваемая локаль, затем её fallbacks, затем `null`, если ни один из них не выдал chunk.
+
+---
+
+## Связанные функции
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getIntlayerAsync.md): Функция, которую вызывают приложения; плагины сборки переписывают её в `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getDictionary.md): Синхронный аналог, принимающий полный словарь.
+- [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md): Collections и variants, а также генерируемые ими карты loader.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

package/docs/ru/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 Функция `getEnumeration` извлекает содержимое, соответствующее определённому количеству, на основе заранее заданных условий в объекте перечисления. Условия определяются в виде ключей, а их приоритет определяется порядком следования в объекте.
 
+Для получения дополнительной информации о том, как объявлять перечисления, см. [документацию по перечислениям](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/enumeration.md).
+
 ## Параметры
 
 - `enumerationContent: QuantityContent<Content>`

package/docs/ru/packages/intlayer/getIntlayer.md

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Документация функции getIntlayer | intlayer
+description: Узнайте, как использовать функцию getIntlayer для пакета intlayer
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Документация: функция `getIntlayer` в `intlayer`
+
+## Описание
+
+Функция `getIntlayer` выбирает один словарь по его ключу и возвращает его содержимое, интерпретированное для заданной локали. Это независимый от фреймворка эквивалент хука `useIntlayer`: то же содержимое, те же селекторы, но пригодный для использования везде, где React контекст недоступен — скрипты Node, серверные функции, загрузчики маршрутов, построители метаданных, обработчики Express/Fastify, тесты.
+
+Функция читает словари, созданные Intlayer в `.intlayer/`, поэтому аргумент `key` типизирован и автодополняется на основе ваших объявлений содержимого, а возвращаемый объект полностью типизирован вплоть до каждого листового узла.
+
+**Основные возможности:**
+
+- Типизированные ключи словарей и типизированное возвращаемое содержимое
+- Интерпретирует каждый узел содержимого (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Принимает локаль или объект селектора (коллекции, варианты)
+- Результаты кэшируются для каждой комбинации `key + locale + selector`
+- В режиме разработки откатывается на безопасный прокси при отсутствии словаря вместо краша
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Обязательно
+  localeOrSelector?: LocalesValues | DictionarySelector, // Опционально
+  plugins?: Plugins[]                         // Опционально
+): DeepTransformContent<...>
+```
+
+---
+
+## Параметры
+
+- `key: DictionaryKeys`
+  - **Description**: Ключ словаря для чтения, объявленный в ваших файлах контента.
+  - **Type**: `DictionaryKeys` — объединение всех объявленных ключей словаря.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Локаль для интерпретации контента или объект селектора для [динамических словарей](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md).
+    - `'fr'` — локаль
+    - `{ item: 2 }` — элемент [коллекции](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/collections.md) (опустите `item` чтобы получить все элементы как массив)
+    - `{ variant: 'black-friday' }` — именованный [вариант](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/variants.md) (опустите для `default` варианта)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — структурированный вариант
+    - Любой селектор может содержать локаль: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — по умолчанию используется настроенная `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Пользовательские трансформеры узлов, заменяющие базовые плагины интерпретатора. Только для продвинутого использования; опустите для сохранения поведения по умолчанию.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Возвращаемое значение
+
+- **Type**: Интерпретированное содержимое словаря, типизированное из вашего объявления.
+- **Description**: Простой объект, отражающий поле `content` вашего словаря, где каждый узел Intlayer разрешен на его финальное значение для запрошенной локали.
+
+---
+
+## Пример использования
+
+### Базовое использование
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      ru: "Привет",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### Без локали
+
+Если пропустить параметр locale, контент будет интерпретирован с использованием `defaultLocale`, объявленной в вашей [конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Интерпретируется с локалью по умолчанию
+```
+
+### Внутри обработчика сервера
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### С селектором (коллекции и варианты)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Один элемент коллекции
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Все элементы коллекции, как упорядоченный массив
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Именованный вариант
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Примечания о поведении
+
+### Кеширование
+
+Результаты кешируются на уровне модуля с ключом `key + locale + selector`. Повторные вызовы `getIntlayer("app", "fr")` интерпретируют словарь один раз и впоследствии возвращают тот же объект.
+
+### Отсутствующие словари
+
+В процессе разработки запрос ключа, для которого не был сгенерирован словарь, регистрирует предупреждение один раз и возвращает безопасный резервный прокси: чтение `content.title` возвращает строку `"app.title"` вместо выброса ошибки. Это позволяет странице оставаться функциональной во время исправления недостающей декларации. Запустите сборку Intlayer (или сервер разработки), чтобы словарь был сгенерирован.
+
+### Размер бандла
+
+`getIntlayer` читает объединённый словарь, который содержит **все** локали. В клиентских бандлах [плагины сборки](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/bundle_optimization.md) переписывают вызов так, чтобы отправлялось только необходимое содержимое. Когда вы читаете содержимое вне рендеринга (метаданные, загрузчики, серверные функции) и хотите загрузить одну локаль по требованию, используйте [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getIntlayerAsync.md).
+
+---
+
+## Связанные функции
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getIntlayerAsync.md): Асинхронный аналог для загрузки одного языкового chunk'а.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/intlayer/getDictionary.md): Интерпретирует объект словаря, который вы передаёте сами, вместо поиска по ключу.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/react-intlayer/useIntlayer.md): Эквивалент React hook'а, читающий локаль из провайдера.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```