@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/uk/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/uk/packages/intlayer/getIntlayer.md), який шукає словник за ключем у згенерованому реєстрі, `getDictionary` приймає сам словник. Це робить його правильним інструментом для вмісту, побудованого під час виконання, отриманого з API або CMS, або оголошеного вбудовано в тесті.
+
+**Основні функції:**
+
+- Працює з будь-яким об'єктом, що слідує структурі словника (`{ key, content }`)
+- Також приймає кваліфіковану групу словника (колекції, варіанти) разом із селектором
+- Повністю типізований: повернений об'єкт відображає `content`, який ви передали
+- Приймає спеціальні плагіни інтерпретатора
+
+---
+
+## Сигнатура функції
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Обов'язково
+  localeOrSelector?: LocalesValues | DictionarySelector, // Опціонально
+  plugins?: Plugins[]                                // Опціонально
+): DeepTransformContent<...>
+```
+
+---
+
+## Параметри
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Опис**: Словник (або кваліфікована група словників) для інтерпретації.
+  - **Тип**: `Dictionary | QualifiedDictionaryGroup`
+  - **Обов'язково**: Так
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Опис**: Мова для інтерпретації вмісту або об'єкт селектора (`{ item }`, `{ variant }`, опціонально з `locale`). Див. [динамічні словники](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md).
+  - **Тип**: `LocalesValues | DictionarySelector`
+  - **Обов'язково**: Ні (Опціонально) — за замовчуванням використовується налаштований `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Опис**: Масив трансформаторів вузлів, які визначають, як інтерпретуються розпізнані вузли. Якщо опущено, використовується стандартний набір плагінів інтерпретатора.
+  - **Тип**: `Plugins[]`
+  - **Обов'язково**: Ні (Опціонально)
+
+### Повертає
+
+- **Тип**: Інтерпретований вміст словника.
+- **Опис**: `content`, яке ви передали, з кожним вузлом Intlayer розв'язаним для запитаної локалі. Для групи колекції без селектора `item` повертається впорядкований масив інтерпретованих записів; `null` повертається, коли селектор не вказує на що-небудь.
+
+---
+
+## Приклад використання
+
+### Базове використання
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        uk: "Привіт",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "uk"
+);
+
+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/uk/packages/intlayer/getIntlayer.md): Та сама інтерпретація, але словник шукається за ключем у сгенерованому реєстрі.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getDictionaryAsync.md): Аналог для карт завантажувачів для кожної мови.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useDictionary.md): Еквівалент React hook, який читає мову з провайдера.
+
+---
+
+## 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/uk/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getDictionaryAsync Function Documentation | intlayer
+description: See how to use the getDictionaryAsync function for intlayer package
+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` завантажує **один локальний чанк** словника та повертає його інтерпретований вміст.
+
+Вона є аналогом [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getDictionary.md) для карт завантажувачів для кожної локалі, виданих в `.intlayer/dynamic_dictionaries/`: замість отримання словника, який містить кожну локаль, вона отримує карту завантажувачів та чекає лише на чанк потрібної локалі.
+
+> У коді застосунку ви зазвичай викликаєте [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayerAsync.md), а не цю функцію. [Плагіни збирання](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/bundle_optimization.md) переписують кожний виклик `getIntlayerAsync('key', locale)` на `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` експортується для користувацьких завантажувачів та для утиліт, які будують власні карти завантажувачів.
+
+**Ключові можливості:**
+
+- Завантажує лише потрібний локальний чанк
+- Підтримує звичайні (`locale → loader`) та кваліфіковані (`locale → qualifierId → loader`) карти завантажувачів
+- Дедублікує одночасне завантаження одного чанка та кешує розв'язаний вміст
+- Невдалі завантаження видаляються з кешу, так що пізніший виклик повторює спробу чанка
+
+---
+
+## Function Signature
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Обов'язково
+  key: string,                                           // Обов'язково
+  localeOrSelector?: LocalesValues | DictionarySelector, // Опціонально
+  plugins?: Plugins[]                                    // Опціонально
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Параметри
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: Карта завантажувачів для кожної локалі. Звичайні карти асоціюють локаль із завантажувачем; кваліфіковані карти (використовуються колекціями та варіантами) асоціюють локаль із ідентифікатором кваліфікатора, а потім із завантажувачем. Для кваліфікованої карти завантажуються лише chunk'и, на які спрямований селектор.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: Ключ словника, використовується для namespace'ування кешу chunk'ів.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Локаль для інтерпретації вмісту або об'єкт селектора (`{ item }`, `{ variant }`, необов'язково з `locale`). Див. [динамічні словники](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/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`, тому одночасні виклики для одного чанку очікують одного завантаження. Відхилене завантаження видаляється з кешу, тому невдалий чанк повторно завантажується при наступному виклику замість того, щоб постійно відтворювати ту саму помилку.
+
+### Fallback за локаллю
+
+Звичайна карта завантажувача проходить по тому ж ланцюжку fallback, що й синхронний режим: спочатку запитана локаль, потім її fallback, потім `null`, якщо жоден з них не видав chunk.
+
+---
+
+## Пов'язані функції
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayerAsync.md): Функція, яку викликають додатки; плаґіни збірки переписують її на `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getDictionary.md): Синхронний аналог, який приймає повний словник.
+- [Динамічні словники](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md): Колекції та варіанти, а також генеровані ними карти завантажувачів.
+
+---
+
+## 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/uk/packages/intlayer/getEnumeration.md

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

package/docs/uk/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**: The key of the dictionary to read, as declared in your content files.
+  - **Type**: `DictionaryKeys` — a union of every declared dictionary key.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object for [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md).
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers replacing the base interpreter plugins. Advanced use only; omit it to keep the default behaviour.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Повертає
+
+- **Тип**: Інтерпретований вміст словника, типізований з вашої декларації.
+- **Опис**: Простий об'єкт, що відображає поле `content` вашого словника, де кожен вузол Intlayer розв'язаний на його остаточне значення для запитуваної мови.
+
+---
+
+## Приклад використання
+
+### Базове використання
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      uk: "Привіт",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### Без локалі
+
+Пропуск локалі інтерпретує вміст за допомогою `defaultLocale`, декларованої у вашій [конфігурації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/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" });
+```
+
+---
+
+## Примітки щодо поведінки
+
+### Caching
+
+Результати кешуються в кеші на рівні модуля за допомогою ключа `key + locale + selector`. Повторне виклик `getIntlayer("app", "fr")` інтерпретує словник один раз і повертає той самий об'єкт потім.
+
+### Відсутні словники
+
+Під час розробки, якщо запросити ключ, для якого не було згенеровано словник, виводиться попередження один раз і повертається безпечний резервний проксі: читання `content.title` повертає рядок `"app.title"` замість викидання помилки. Це дозволяє сторінці залишатися функціональною, поки відсутня декларація не буде виправлена. Запустіть збірку Intlayer (або dev сервер), щоб словник був згенеровано.
+
+### Розмір bundle
+
+`getIntlayer` читає об'єднаний словник, який містить **кожну** локаль. У клієнтських bundle'ах [плагіни збірки](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/bundle_optimization.md) переписують виклик, щоб відправляється тільки необхідний контент. Коли ви читаєте контент поза рендерингом (метадані, loader'и, серверні функції) і хочете, щоб одна локаль завантажувалася за запитом, використовуйте замість цього [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayerAsync.md).
+
+---
+
+## Пов'язані функції
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayerAsync.md): Асинхронний аналог для завантаження одного chunk'у локалізації.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getDictionary.md): Інтерпретує об'єкт dictionary, який ви передаєте самі, замість пошуку за ключем.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/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>
+>;
+```

package/docs/uk/packages/intlayer/getIntlayerAsync.md

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Документація функції getIntlayerAsync | intlayer
+description: Дізнайтеся, як використовувати функцію getIntlayerAsync з пакета intlayer
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Документація: функція `getIntlayerAsync` в `intlayer`
+
+## Опис
+
+Функція `getIntlayerAsync` вибирає один словник за його ключем і розв'язує його вміст для заданої локалі, **завантажуючи тільки цю локаль**.
+
+Це асинхронний аналог [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayer.md), призначений для місць, де словник читається поза рендеруванням — маршрути `head` / конструктори метаданих, лодери, серверні функції.
+
+Де `getIntlayer` завантажує об'єднаний словник, що містить кожну локаль, [плагіни збірки](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) переписують цей виклик у `getDictionaryAsync(loaderMap, key, locale)`, спрямовуючи його на фрагменти для кожної локалі в `.intlayer/dynamic_dictionaries/`. Таким чином, пакет ніколи не містить нічого, крім фактично запитаної локалі.
+
+Без цих плагінів — необоптимізована збірка — виклик розв'язується через синхронний реєстр словників: той же вміст, але без поділу по локалях.
+
+**Ключові особливості:**
+
+- Ті самі типізовані ключі, селектори та повернений вміст, що й у `getIntlayer`
+- Завантажує тільки запитаний фрагмент локалі в оптимізованих збірках
+- Одночасні виклики для одного й того ж фрагмента діляться одним завантаженням
+- Безпечна для використання в асинхронних конструкторах метаданих, лодерах та серверних функціях
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Обов'язковий
+  localeOrSelector?: LocalesValues | DictionarySelector, // Необов'язковий
+  plugins?: Plugins[]                         // Необов'язковий
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Параметри
+
+- `key: DictionaryKeys`
+  - **Опис**: Ключ словника для читання, як оголошено у ваших файлах вмісту.
+  - **Тип**: `DictionaryKeys` — об'єднання всіх оголошених ключів словника.
+  - **Обов'язково**: Так
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Опис**: Локаль для інтерпретації вмісту або об'єкт селектора для [динамічних словників](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md).
+    - `'fr'` — локаль
+    - `{ item: 2 }` — елемент [колекції](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/collections.md) (пропустіть `item`, щоб отримати кожен елемент як масив)
+    - `{ variant: 'black-friday' }` — названий [варіант](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/variants.md) (пропустіть для `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — структурований варіант
+    - Будь-який селектор може містити локаль: `{ item: 2, locale: 'fr' }`
+  - **Тип**: `LocalesValues | DictionarySelector`
+  - **Обов'язково**: Ні (Опціонально) — за замовчуванням використовується налаштована `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Опис**: Користувацькі трансформатори вузлів, що замінюють базові плагіни інтерпретатора. Тільки для розширеного використання.
+  - **Тип**: `Plugins[]`
+  - **Обов'язково**: Ні (Опціонально)
+
+### Повертає
+
+- **Тип**: `Promise<Content>` — promise, що розв'язується в інтерпретований вміст словника, типізований на основі вашої декларації.
+
+---
+
+## Приклад використання
+
+### Базове використання
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` vs `getIntlayerAsync`
+
+|                    | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                 |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Returns            | Вміст                                                                                                           | Promise вмісту                                     |
+| Dictionary loaded  | Об'єднаний словник (усі локалі)                                                                                 | Фрагмент тільки запитаної локалі                   |
+| Best suited for    | Rendering, синхронні кодові шляхи                                                                               | Metadata, loaders, серверні функції                |
+| Requires a plugin? | No                                                                                                              | No — розділення за локалями потребує build plugins |
+
+Обидві функції приймають однакові аргументи та повертають один і той же вміст: перемикання між ними змінює лише **коли** та **скільки** завантажується.
+
+---
+
+## Пов'язані функції
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getIntlayer.md): Синхронний еквівалент, який читає об'єднаний словник.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getDictionaryAsync.md): Низькорівнева функція, яку переписують плагіни збірки.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getLocale.md): Визначає локаль вхідного запиту.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```