@intlayer/docs 9.5.4-canary.0 → 9.5.5

package/docs/uk/packages/astro-intlayer/exports.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
-title: Пакет astro-intlayer
-description: Інтеграція Astro для Intlayer, що забезпечує налаштування маршрутизації на основі локалі та керування словниками.
+updatedAt: 2026-09-19
+title: Документація пакета astro-intlayer
+description: Інтеграція Astro для Intlayer, що забезпечує маршрутизацію на основі локалей, middleware, хуки, клієнтське сховище та керування словниками.
 keywords:
   - astro-intlayer
   - astro
@@ -14,6 +14,9 @@ slugs:
   - astro-intlayer
   - exports
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Додано документацію для хуків useIntlayer, useDictionary, useLocale, middleware та форматерів"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Уніфікована документація для всіх експортів"
@@ -22,7 +25,7 @@ author: aymericzip
 
 # Пакет astro-intlayer
 
-Пакет `astro-intlayer` надає необхідні інструменти для інтеграції Intlayer у додатки Astro. Він налаштовує маршрутизацію на основі локалі та керування словниками.
+Пакет `astro-intlayer` надає необхідні інструменти для інтеграції Intlayer у додатки Astro. Він налаштовує маршрутизацію на основі локалей, керування словниками, переписування сторінок під час збирання, middleware запитів та хуки для доступу до багатомовного контенту як у компонентах `.astro`, що рендеряться на сервері, так і в клієнтських скриптах.
 
 ## Встановлення
 
@@ -34,22 +37,171 @@ npm install astro-intlayer
 
 ### Інтеграція
 
-Пакет `astro-intlayer` надає інтеграцію для Astro для налаштування Intlayer у вашому проєкті.
+Пакет `astro-intlayer` надає інтеграцію Astro, яка налаштовує Intlayer у вашому проекті.
 
 Імпорт:
 
 ```tsx
-import "astro-intlayer";
+import { intlayer } from "astro-intlayer";
 ```
 
-або додайте в `astro.config.mjs`:
+або імпорт за замовчуванням у `astro.config.mjs`:
 
 ```ts
+import { defineConfig } from "astro/config";
+import intlayer from "astro-intlayer";
+
 export default defineConfig({
   integrations: [intlayer()],
 });
 ```
 
-| Функція    | Опис                                                            |
-| ---------- | --------------------------------------------------------------- |
-| `intlayer` | Інтеграція для Astro, яка налаштовує Intlayer у вашому проєкті. |
+| Функція    | Опис                                                                                                                                                                                                            | Пов'язана документація                                                                                        |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Інтеграція Astro, яка готує словники, налаштовує плагіни Vite (псевдоніми, проксі маршрутизації, оптимізацію збирання), автоматично реєструє middleware та створює пререндерені сторінки за локалізованими URL. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/intlayer.md) |
+
+### Хуки (Сервер та Клієнт)
+
+Імпорт:
+
+```tsx
+import { useIntlayer, useDictionary, useLocale } from "astro-intlayer";
+```
+
+| Хук             | Опис                                                                                                                                                                           | Пов'язана документація                                                                                                  |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | Отримує словник за ключем і повертає локалізований контент. У frontmatter `.astro` зчитує локаль запиту з `Astro.locals`. У клієнтському `<script>` зчитує зі сховища клієнта. | [useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useIntlayer.md)     |
+| `useDictionary` | Перетворює об'єкт словника та повертає вміст для визначеної локалі. Працює як у frontmatter, так і в клієнтських скриптах.                                                     | [useDictionary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useDictionary.md) |
+| `useLocale`     | Повертає поточну локаль, локаль за замовчуванням, доступні локалі та функцію для оновлення локалі.                                                                             | [useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useLocale.md)         |
+
+### Middleware (astro-intlayer/middleware)
+
+Імпорт:
+
+```tsx
+import { onRequest } from "astro-intlayer/middleware";
+```
+
+| Експорт     | Тип                 | Опис                                                                                                                                                        | Пов'язана документація                                                                                          |
+| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `onRequest` | `MiddlewareHandler` | Middleware Astro, яке визначає локаль запиту та додає `Astro.locals.intlayer`. Реєструється автоматично через `intlayer()` або імпортується для композиції. | [onRequest](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/onRequest.md) |
+
+### Утиліти
+
+Імпорт:
+
+```tsx
+import { getIntlayerLocals } from "astro-intlayer";
+```
+
+| Функція             | Опис                                                                                                            | Пов'язана документація |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `getIntlayerLocals` | Допоміжна функція для отримання поточного об'єкта `IntlayerLocals` з контексту запиту поза межами Astro.locals. | -                      |
+
+### Клієнтські утиліти (astro-intlayer/client)
+
+Імпорт:
+
+```tsx
+import {
+  useIntlayer,
+  useDictionary,
+  useDictionaryDynamic,
+  useLocale,
+  useLocaleStorage,
+  useLocaleCookie,
+  getIntlayer,
+  getDictionary,
+  installIntlayer,
+  setLocaleInStorage,
+  setLocaleCookie,
+  localeInStorage,
+  localeCookie,
+} from "astro-intlayer/client";
+```
+
+При імпорті в браузері або всередині тегів `<script>` клієнта, `astro-intlayer` автоматично перенаправляється на `astro-intlayer/client` (на базі `vanilla-intlayer`), надаючи клієнтські гетери словників, підписки на сховище та інструменти збереження локалі.
+
+### Форматери (astro-intlayer/format)
+
+Імпорт:
+
+```tsx
+import {
+  useIntl,
+  useDate,
+  useNumber,
+  useCurrency,
+  usePercentage,
+  useRelativeTime,
+  useList,
+  useUnit,
+  useCompact,
+} from "astro-intlayer/format";
+```
+
+| Хук               | Опис                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------- |
+| `useIntl`         | Повертає екземпляр Intl, прив'язаний до локалі запиту або клієнта, з можливістю кешування та підписки.    |
+| `useDate`         | Повертає функцію форматування дати, прив'язану до поточної локалі (`Intl.DateTimeFormat`).                |
+| `useNumber`       | Повертає функцію форматування чисел, прив'язану до поточної локалі (`Intl.NumberFormat`).                 |
+| `useCurrency`     | Повертає функцію форматування валюти, прив'язану до поточної локалі.                                      |
+| `usePercentage`   | Повертає функцію форматування відсотків, прив'язану до поточної локалі.                                   |
+| `useRelativeTime` | Повертає функцію форматування відносного часу, прив'язану до поточної локалі (`Intl.RelativeTimeFormat`). |
+| `useList`         | Повертає функцію форматування списків, прив'язану до поточної локалі (`Intl.ListFormat`).                 |
+| `useUnit`         | Повертає функцію форматування одиниць вимірювання, прив'язану до поточної локалі.                         |
+| `useCompact`      | Повертає функцію компактного форматування чисел, прив'язану до поточної локалі (наприклад, `1.5K`).       |
+
+### Утиліти HTML (astro-intlayer/html)
+
+Імпорт:
+
+```tsx
+import { renderHTML, useHTML, useHTMLRenderer } from "astro-intlayer/html";
+```
+
+| Експорт           | Тип        | Опис                                                               |
+| ----------------- | ---------- | ------------------------------------------------------------------ |
+| `renderHTML`      | `Function` | Автономна утиліта для рендерингу вузлів HTML.                      |
+| `useHTML`         | `Hook`     | Хук для отримання контексту постачальника HTML та конфігурації.    |
+| `useHTMLRenderer` | `Hook`     | Хук для отримання попередньо налаштованої функції рендерингу HTML. |
+
+### Утиліти Markdown (astro-intlayer/markdown)
+
+Імпорт:
+
+```tsx
+import {
+  compileMarkdown,
+  renderMarkdown,
+  parseMarkdown,
+  useMarkdown,
+  useMarkdownRenderer,
+} from "astro-intlayer/markdown";
+```
+
+| Експорт               | Тип        | Опис                                                                   |
+| --------------------- | ---------- | ---------------------------------------------------------------------- |
+| `compileMarkdown`     | `Function` | Компілює рядки markdown у структуроване представлення.                 |
+| `renderMarkdown`      | `Function` | Рендерить вміст markdown у вихідні вузли.                              |
+| `parseMarkdown`       | `Function` | Аналізує необроблений вміст markdown у дерево AST.                     |
+| `useMarkdown`         | `Hook`     | Хук для отримання контексту постачальника markdown.                    |
+| `useMarkdownRenderer` | `Hook`     | Хук для отримання попередньо налаштованої функції рендерингу Markdown. |
+
+### Типи
+
+Імпорт:
+
+```tsx
+import type {
+  IntlayerLocals,
+  UseLocaleProps,
+  UseLocaleResult,
+} from "astro-intlayer";
+```
+
+| Тип               | Опис                                                                                                         |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `IntlayerLocals`  | Об'єкт, прикріплений до `Astro.locals.intlayer`, що містить `locale`, `defaultLocale` та `availableLocales`. |
+| `UseLocaleProps`  | Необов'язкові властивості конфігурації, які приймає `useLocale()`.                                           |
+| `UseLocaleResult` | Тип повернення `useLocale()`, що надає властивості локалі та методи її оновлення.                            |

package/docs/uk/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: Документація інтеграції intlayer | astro-intlayer
+description: Дізнайтеся, як налаштувати та використовувати інтеграцію Astro intlayer у файлі astro.config.mjs.
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - інтеграція
+  - i18n
+  - Інтернаціоналізація
+  - Документація
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Оновлено документацію інтеграції з деталями про middleware та хуки"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "Ініціалізація документації"
+author: aymericzip
+---
+
+# Документація інтеграції Astro intlayer
+
+Інтеграція `intlayer` для Astro налаштовує ваш проект для багатомовної інтернаціоналізації (i18n). Вона відповідає за підготовку словників під час збирання, додавання плагінів Vite, автоматичну реєстрацію middleware запитів та створення локалізованих пререндерених сторінок.
+
+## Використання
+
+Додайте `intlayer()` до вашого `astro.config.mjs`:
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+Команда codemod Astro CLI (`astro add astro-intlayer`) також створює імпорт за замовчуванням, який повністю підтримується:
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## Опис
+
+Інтеграція підключається до життєвого циклу збирання та виконання Astro:
+
+1. **Налаштування конфігурації (`astro:config:setup`)**:
+   - **Підготовка словників**: Готує словники Intlayer та згенеровані типи перед запуском збирання.
+   - **Плагіни Vite**: Додає плагіни для псевдонімів Vite (забезпечуючи зручний імпорт словників), проксі маршрутизації локалей та оптимізації коду.
+   - **Реєстрація Middleware**: Автоматично додає `astro-intlayer/middleware` до ланцюжка middleware проекту, заповнюючи `Astro.locals.intlayer` для кожного вхідного запиту.
+2. **Завершення збирання (`astro:build:done`)**:
+   - **Переписування сторінок**: Аналізує правила переписування локалізованих URL-адрес та генерує пререндерені сторінки HTML за відповідними локалізованими шляхами.
+
+## Що надається "з коробки"
+
+Після налаштування ваш додаток Astro може одразу використовувати:
+
+- Хуки `useIntlayer`, `useDictionary` та `useLocale` всередині frontmatter компонентів `.astro`.
+- Об'єкт `Astro.locals.intlayer` в ендпоінтах та сторінках Astro.
+- Клієнтські імпорти в блоках `<script>`, які дублюють той самий API з реактивними оновленнями.
+- Вбудовані форматери в `astro-intlayer/format` (`useDate`, `useNumber`, `useCurrency` тощо).
+
+## Пов'язана документація
+
+- [Хук `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useIntlayer.md)
+- [Хук `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useLocale.md)
+- [Middleware `onRequest`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/onRequest.md)

package/docs/uk/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Документація middleware onRequest | astro-intlayer
+description: Дізнайтеся, як використовувати middleware onRequest у додатках Astro для визначення локалі запиту та заповнення Astro.locals.intlayer.
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - Інтернаціоналізація
+  - Документація
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Ініціалізація документації"
+author: aymericzip
+---
+
+# Документація middleware Astro onRequest
+
+Middleware `onRequest` з `astro-intlayer/middleware` визначає локаль кожного вхідного HTTP-запиту та заповнює `Astro.locals.intlayer`.
+
+Коли ви реєструєте інтеграцію `intlayer()` у `astro.config.mjs`, це middleware додається автоматично. Його потрібно імпортувати напряму лише в тому випадку, якщо ви компонуєте middleware Astro вручну за допомогою `sequence(...)`.
+
+## Використання
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // Доступ до визначеної локалі у власному middleware
+  const { locale } = context.locals.intlayer;
+  console.log(`Обробка запиту для локалі: ${locale}`);
+
+  return next();
+});
+```
+
+## Опис
+
+Middleware виконує такі завдання:
+
+1. **Визначення локалі**:
+   - **URL**: Аналізує префікс шляху URL або параметр пошуку `?locale=` (якщо `routing.mode` не встановлено в `no-prefix`).
+   - **Кукі / Заголовки**: Перевіряє збережені кукі локалі або значення власних заголовків.
+   - **Accept-Language**: Використовує мовні налаштування браузера за відсутності попередніх даних.
+   - Для пререндерених сторінок (`context.isPrerendered`) локаль витягується виключно з URL-адреси, щоб уникнути попереджень збирання Astro.
+2. **Заповнення контексту**: Заповнює `Astro.locals.intlayer` наступними даними:
+   - `locale`: Визначена локаль.
+   - `defaultLocale`: Резервна локаль за замовчуванням.
+   - `availableLocales`: Масив налаштованих локалей.
+3. **Область AsyncLocalStorage**: Обгортає подальшу обробку запиту в область `AsyncLocalStorage`, дозволяючи функціям `useIntlayer()`, `useDictionary()` та `useLocale()` отримувати стан запиту без передачі аргументів.
+
+## Тип `IntlayerLocals`
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## Пов'язана документація
+
+- [Інтеграція `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/intlayer.md)
+- [Хук `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useIntlayer.md)
+- [Хук `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useLocale.md)

package/docs/uk/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Документація хука useDictionary | astro-intlayer
+description: Дізнайтеся, як використовувати хук useDictionary у компонентах і скриптах Astro для обробки об'єктів словників.
+keywords:
+  - useDictionary
+  - словник
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Інтернаціоналізація
+  - Документація
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Ініціалізація документації"
+author: aymericzip
+---
+
+# Документація хука useDictionary
+
+Хук `useDictionary` обробляє імпортований або визначений безпосередньо в коді об'єкт словника та повертає його вміст для поточної локалі в додатках Astro.
+
+На відміну від `useIntlayer`, який отримує словники за ключем із глобального реєстру словників, `useDictionary` працює безпосередньо з об'єктом словника.
+
+## Використання
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+Ви також можете передавати вбудовані словники, визначені за допомогою `t()`:
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      uk: "Усі права захищені.",
+      en: "All rights reserved.",
+      fr: "Tous droits réservés.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## Параметри
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**: Об'єкт словника або кваліфікована група словників.
+2. **`localeOrSelector`** (необов'язково): Конкретна локаль або об'єкт селектора (`{ item }`, `{ variant }`, додатково з `locale`).
+
+## Опис
+
+Хук виконує такі завдання:
+
+1. **Визначення локалі**: На сервері отримує локаль з `Astro.locals.intlayer`. У браузері використовує локаль клієнтського сховища.
+2. **Обробка вмісту**: Перетворює переклади (`t()`), перерахування, умови та вкладені структури відповідно до визначеної локалі.
+3. **Селектори**: Застосовує будь-які селектори елементів або варіантів, передані в аргументах.
+
+## Пов'язана документація
+
+- [Інтеграція `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/intlayer.md)
+- [Хук `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useIntlayer.md)
+- [Хук `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useLocale.md)

package/docs/uk/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Документація хука useIntlayer | astro-intlayer
+description: Дізнайтеся, як використовувати хук useIntlayer у компонентах Astro та клієнтських скриптах для доступу до локалізованого вмісту.
+keywords:
+  - useIntlayer
+  - словник
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Інтернаціоналізація
+  - Документація
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Ініціалізація документації"
+author: aymericzip
+---
+
+# Документація хука useIntlayer
+
+Хук `useIntlayer` дозволяє отримувати локалізований вміст словника за ключем у додатках Astro.
+
+Його можна викликати у двох різних контекстах за одним і тим самим шляхом імпорту:
+
+1. **Сервер / Frontmatter**: Усередині файлів `.astro` він автоматично визначає вміст за допомогою локалі запиту, збереженої в `Astro.locals.intlayer`.
+2. **Браузер / Клієнтський скрипт `<script>`**: Усередині клієнтських скриптів або компонентів UI-фреймворків він звертається до реалізації клієнтського сховища (`vanilla-intlayer`).
+
+## Використання
+
+### У Frontmatter компонента Astro
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### У клієнтських блоках `<script>`
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## Параметри
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**: Унікальний ключ словника (як визначено у ваших файлах декларацій `.content.ts`).
+2. **`localeOrSelector`** (необов'язково): Конкретна локаль або об'єкт селектора (`{ item }`, `{ variant }`, додатково з `locale`). Якщо вказано, він перевизначає локаль, визначену з контексту запиту або клієнтського сховища.
+
+## Опис
+
+Хук виконує такі завдання:
+
+1. **Визначення локалі**:
+   - На сервері зчитує активну локаль з `Astro.locals.intlayer` через область `AsyncLocalStorage`, ініціалізовану `astro-intlayer/middleware`.
+   - У браузері зчитує активну локаль зі сховища клієнта.
+2. **Отримання словника**: Впроваджує вміст словника, що відповідає вказаному ключу.
+3. **Обробка перекладу**: Перетворює переклади (`t()`), перерахування, умови та markdown у готовий до рендерингу вміст.
+
+## Пов'язана документація
+
+- [Інтеграція `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/intlayer.md)
+- [Хук `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useDictionary.md)
+- [Хук `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/astro-intlayer/useLocale.md)