@intlayer/docs 8.0.0 → 8.0.1-canary.0

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

@@ -0,0 +1,50 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Документація пакета adonis-intlayer
+description: Проміжне ПЗ AdonisJS для Intlayer, що надає функції перекладу та визначення локалі.
+keywords:
+  - adonis-intlayer
+  - adonisjs
+  - middleware
+  - інтернаціоналізація
+  - i18n
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Початкова документація
+---
+
+# Пакет adonis-intlayer
+
+Пакет `adonis-intlayer` надає проміжне ПЗ для додатків AdonisJS для обробки інтернаціоналізації. Він визначає локаль користувача та надає функції перекладу.
+
+## Встановлення
+
+```bash
+npm install adonis-intlayer
+```
+
+## Експорт
+
+### Проміжне ПЗ (Middleware)
+
+Пакет надає проміжне ПЗ AdonisJS для обробки інтернаціоналізації.
+
+| Функція              | Опис                                                                                                                                                                                                                                                                                  | Відповідна документація                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `IntlayerMiddleware` | Проміжне ПЗ AdonisJS, яке визначає локаль користувача та заповнює контекст запиту даними Intlayer. Воно також налаштовує простір імен CLS (Async Local Storage) для доступу до життєвого циклу запиту, дозволяючи використовувати глобальні функції, такі як `t`, `getIntlayer` тощо. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/adonis-intlayer/intlayer.md) |
+
+### Функції
+
+| Функція         | Опис                                                                                                                                                                                                           | Відповідна документація                                                                                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Функція перекладу, яка отримує контент для поточної локалі. Працює в межах життєвого циклу запиту, керованого проміжним ПЗ `intlayer`. Використовує CLS (Async Local Storage) для доступу до контексту запиту. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/translation.md) |
+| `getIntlayer`   | Отримує словник за його ключем зі згенерованої декларації та повертає його вміст для вказаної локалі. Оптимізована версія `getDictionary`. Використовує CLS для доступу до контексту запиту.                   | -                                                                                                      |
+| `getDictionary` | Обробляє об'єкти словника та повертає вміст для вказаної локалі. Обробляє переклади `t()`, перерахування, markdown, HTML тощо. Використовує CLS для доступу до контексту запиту.                               | -                                                                                                      |
+| `getLocale`     | Отримує поточну локаль із контексту запиту за допомогою CLS.                                                                                                                                                   | -                                                                                                      |

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

@@ -0,0 +1,54 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Документація проміжного ПЗ intlayer для AdonisJS | adonis-intlayer
+description: Дізнайтеся, як використовувати проміжне ПЗ intlayer для пакета adonis-intlayer
+keywords:
+  - intlayer
+  - adonisjs
+  - middleware
+  - Intlayer
+  - інтернаціоналізація
+  - документація
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Початкова документація
+---
+
+# Документація проміжного ПЗ intlayer для AdonisJS
+
+Проміжне ПЗ `intlayer` для AdonisJS визначає локаль користувача та надає функції перекладу через контекст запиту. Воно також дозволяє використовувати глобальні функції перекладу в межах потоку запиту.
+
+## Використання
+
+```ts fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+```ts fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Hello",
+    fr: "Bonjour",
+  });
+});
+```
+
+## Опис
+
+Проміжне ПЗ виконує наступні завдання:
+
+1. **Визначення локалі**: Воно аналізує запит (заголовки, куки тощо), щоб визначити бажану локаль користувача.
+2. **Налаштування контексту**: Воно заповнює контекст запиту інформацією про локаль.
+3. **Async Local Storage**: Воно використовує `cls-hooked` для управління асинхронним контекстом, дозволяючи глобальним функціям Intlayer, таким як `t`, `getIntlayer` та `getDictionary`, отримувати доступ до локалі конкретного запиту без її ручної передачі.
+
+> Примітка: Щоб використовувати куки для визначення локалі, переконайтеся, що `@adonisjs/cookie` налаштовано та використовується у вашому додатку.

package/docs/uk/packages/adonis-intlayer/t.md

@@ -0,0 +1,149 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Документація функції t | adonis-intlayer
+description: Дізнайтеся, як використовувати функцію t для пакета adonis-intlayer
+keywords:
+  - t
+  - переклад
+  - Intlayer
+  - інтернаціоналізація
+  - документація
+  - AdonisJS
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - t
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Початкова документація
+---
+
+# Документація: Функція `t` в `adonis-intlayer`
+
+Функція `t` у пакеті `adonis-intlayer` є основною утилітою для надання локалізованих відповідей у вашому додатку AdonisJS. Вона спрощує інтернаціоналізацію (i18n) на основі бажаної мови користувача.
+
+---
+
+## Огляд
+
+Функція `t` використовується для визначення та отримання перекладів для заданого набору мов. Вона автоматично визначає відповідну мову для повернення на основі налаштувань запиту клієнта, таких як заголовок `Accept-Language`. Якщо бажана мова недоступна, вона плавно переключається на локаль за замовчуванням, зазначену у вашій конфігурації.
+
+---
+
+## Ключові особливості
+
+- **Динамічна локалізація**: Автоматично вибирає найбільш підходящий переклад для клієнта.
+- **Резервна локаль (Fallback)**: Повертається до локалі за замовчуванням, якщо бажана мова клієнта недоступна, забезпечуючи безперервність користувацького досвіду.
+- **Асинхронний контекст**: Безперешкодно працює в рамках життєвого циклу запиту AdonisJS з використанням Async Local Storage.
+- **Підтримка TypeScript**: Забезпечує типізацію для ваших перекладів.
+
+---
+
+## Сигнатура функції
+
+```typescript
+t(translations: Record<string, any>): any;
+```
+
+### Параметри
+
+- `translations`: Об'єкт, де ключами є коди локалей (наприклад, `en`, `fr`, `es`), а значеннями — відповідний перекладений контент.
+
+### Повертає
+
+- Контент, що відповідає бажаній мові клієнта.
+
+---
+
+## Завантаження проміжного ПЗ (Middleware)
+
+Щоб функція `t` працювала правильно, ви **повинні** зареєструвати проміжне ПЗ `intlayer` у вашому додатку AdonisJS.
+
+```typescript fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+---
+
+## Приклади використання
+
+### Базовий приклад
+
+```typescript fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Welcome!",
+    fr: "Bienvenue!",
+    es: "¡Bienvenido!",
+  });
+});
+```
+
+### Використання в контролерах
+
+```typescript fileName="app/controllers/example_controller.ts"
+import type { HttpContext } from "@adonisjs/core/http";
+import { t } from "adonis-intlayer";
+
+export default class ExampleController {
+  async index({ response }: HttpContext) {
+    return response.send(
+      t({
+        en: "Hello from controller",
+        fr: "Bonjour з контролера",
+      })
+    );
+  }
+}
+```
+
+---
+
+## Просунуті теми
+
+### Механізм Fallback
+
+Якщо бажана локаль недоступна, функція `t` повернеться до локалі за замовчуванням, визначеної у вашому файлі `intlayer.config.ts`.
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.RUSSIAN,
+      Locales.JAPANESE,
+      Locales.FRENCH,
+      Locales.KOREAN,
+      Locales.CHINESE,
+      Locales.SPANISH,
+      Locales.GERMAN,
+      Locales.ARABIC,
+      Locales.ITALIAN,
+      Locales.ENGLISH_UNITED_KINGDOM,
+      Locales.PORTUGUESE,
+      Locales.HINDI,
+      Locales.TURKISH,
+      Locales.POLISH,
+      Locales.INDONESIAN,
+      Locales.VIETNAMESE,
+      Locales.UKRAINIAN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+### Інтеграція з TypeScript
+
+Функція `t` є типізованою при використанні з визначеними словниками. Для отримання більш детальної інформації зверніться до [документації TypeScript](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md).

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

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: Документація пакета hono-intlayer
+description: Проміжне ПЗ Hono для Intlayer, що надає функції перекладу та виявлення локалі.
+keywords:
+  - hono-intlayer
+  - hono
+  - middleware
+  - інтернаціоналізація
+  - i18n
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: Уніфікована документація для всіх експортів
+---
+
+# Пакет hono-intlayer
+
+Пакет `hono-intlayer` надає проміжне програмне забезпечення (middleware) для додатків Hono для обробки інтернаціоналізації. Він виявляє локаль користувача та заповнює об'єкт контексту.
+
+## Встановлення
+
+```bash
+npm install hono-intlayer
+```
+
+## Експорти
+
+### Проміжне ПЗ (Middleware)
+
+Імпорт:
+
+```tsx
+import { intlayer } from "hono-intlayer";
+```
+
+| Функція    | Опис                                                                                                                                                                                                                                                                                  | Пов'язана док.                                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `intlayer` | Проміжне ПЗ Hono, яке інтегрує Intlayer у ваш додаток Hono. Обробляє виявлення локалі зі сховища (cookies, заголовки), заповнює контекст функціями `t`, `getIntlayer` та `getDictionary`, а також налаштовує простір імен CLS для програмного доступу під час життєвого циклу запиту. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/hono-intlayer/intlayer.md) |
+
+### Функції
+
+Імпорт:
+
+```tsx
+import { t, getIntlayer, getDictionary } from "hono-intlayer";
+```
+
+| Функція         | Опис                                                                                                                                                                                                                             | Пов'язана док.                                                                                      |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `t`             | Глобальна функція перекладу, яка отримує вміст для поточної локалі в Hono. Використовує CLS (Async Local Storage) і має використовуватися в контексті запиту, керованому проміжним ПЗ `intlayer`. Також доступна через контекст. | [переклад](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/translation.md) |
+| `getIntlayer`   | Отримує словник за його ключем зі згенерованої декларації та повертає його вміст для вказаної локалі. Оптимізована версія `getDictionary`. Використовує CLS для доступу до контексту запиту. Також доступна через контекст.      | -                                                                                                   |
+| `getDictionary` | Обробляє об'єкти словника та повертає вміст для вказаної локалі. Обробляє переклади `t()`, перерахування, markdown, HTML тощо. Використовує CLS для доступу до контексту запиту. Також доступна через контекст.                  | -                                                                                                   |

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

@@ -0,0 +1,60 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: Документація проміжного ПЗ intlayer для Hono | hono-intlayer
+description: Дізнайтеся, як використовувати проміжне ПЗ intlayer для пакета hono-intlayer
+keywords:
+  - intlayer
+  - hono
+  - middleware
+  - Intlayer
+  - інтернаціоналізація
+  - документація
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: Ініціалізація док.
+---
+
+# Документація проміжного ПЗ intlayer для Hono
+
+Проміжне ПЗ `intlayer` для Hono виявляє локаль користувача та заповнює об'єкт контексту функціями Intlayer. Воно також дозволяє використовувати глобальні функції перекладу в контексті запиту.
+
+## Використання
+
+```ts
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+app.use("*", intlayer());
+
+app.get("/", async (c) => {
+  const t = c.get("t");
+  const content = t({
+    en: "Hello",
+    fr: "Bonjour",
+    uk: "Привіт",
+  });
+
+  return c.text(content);
+});
+```
+
+## Опис
+
+Проміжне ПЗ виконує такі завдання:
+
+1. **Виявлення локалі**: аналізує запит (заголовки, куки тощо) для визначення бажаної локалі користувача.
+2. **Заповнення контексту**: додає дані Intlayer до контексту Hono, доступні через `c.get()`. Сюди входять:
+   - `locale`: виявлена локаль.
+   - `t`: функція перекладу.
+   - `getIntlayer`: функція для отримання словників.
+   - `getDictionary`: функція для обробки об'єктів словника.
+3. **Управління контекстом**: використовує `cls-hooked` для управління асинхронним контекстом, дозволяючи глобальним функціям Intlayer (`t`, `getIntlayer`, `getDictionary`) отримувати доступ до локалі, специфічної для запиту, без передачі об'єкта контексту.

package/docs/uk/packages/hono-intlayer/t.md

@@ -0,0 +1,268 @@
+---
+createdAt: 2024-12-02
+updatedAt: 2025-06-29
+title: Документація функції t | hono-intlayer
+description: Дізнайтеся, як використовувати функцію t для пакета hono-intlayer
+keywords:
+  - t
+  - переклад
+  - Intlayer
+  - інтернаціоналізація
+  - документація
+  - Hono
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Документація: функція `t` у `hono-intlayer`
+
+Функція `t` у пакеті `hono-intlayer` є основним інструментом для надання локалізованих відповідей у вашому додатку Hono. Вона спрощує інтернаціоналізацію (i18n), динамічно вибираючи вміст на основі бажаної мови користувача.
+
+---
+
+## Огляд
+
+Функція `t` використовується для визначення та отримання перекладів для заданого набору мов. Вона автоматично визначає відповідну мову для повернення на основі налаштувань запиту клієнта, таких як заголовок `Accept-Language`. Якщо бажана мова недоступна, вона плавно повертається до мови за замовчуванням, указаної у вашій конфігурації.
+
+---
+
+## Ключові особливості
+
+- **Динамічна локалізація**: автоматично вибирає найбільш підходящий переклад для клієнта.
+- **Повернення до мови за замовчуванням**: повертається до локалі за замовчуванням, якщо бажана мова клієнта недоступна, забезпечуючи безперервність користувацького досвіду.
+- **Легкість і швидкість**: розроблено для високопродуктивних додатків, що забезпечує мінімальні накладні витрати.
+- **Підтримка суворого режиму**: забезпечує суворе дотримання оголошених локалей для надійної поведінки.
+
+---
+
+## Сигнатура функції
+
+```typescript
+t(translations: Record<string, string>): string;
+```
+
+### Параметри
+
+- `translations`: об'єкт, де ключі — це коди локалей (наприклад, `en`, `fr`, `uk`), а значення — відповідні перекладені рядки.
+
+### Повертає
+
+- Рядок, що представляє вміст бажаною мовою клієнта.
+
+---
+
+## Завантаження обробника запитів інтернаціоналізації
+
+Щоб забезпечити коректну роботу функцій інтернаціоналізації, що надаються `hono-intlayer`, ви **повинні** завантажити проміжне програмне забезпечення (middleware) інтернаціоналізації на початку вашого додатка Hono. Це активує функцію `t` і забезпечує належну обробку виявлення локалі та перекладу.
+
+Розмістіть проміжне ПЗ `app.use("*", intlayer())` **перед будь-якими маршрутами** у вашому додатку, щоб усі маршрути могли скористатися перевагами інтернаціоналізації:
+
+```typescript {6} fileName="src/index.ts" codeFormat="typescript"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// Завантаження обробника запитів інтернаціоналізації
+app.use("*", intlayer());
+
+// Визначайте свої маршрути після завантаження проміжного ПЗ
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      uk: "Привіт, світе!",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.mjs" codeFormat="esm"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// Завантаження обробника запитів інтернаціоналізації
+app.use("*", intlayer());
+
+// Визначайте свої маршрути після завантаження проміжного ПЗ
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      uk: "Привіт, світе!",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.cjs" codeFormat="commonjs"
+const { Hono } = require("hono");
+const { intlayer, t } = require("hono-intlayer");
+
+const app = new Hono();
+
+// Завантаження обробника запитів інтернаціоналізації
+app.use("*", intlayer());
+
+// Визначайте свої маршрути після завантаження проміжного ПЗ
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      uk: "Привіт, світе!",
+    })
+  );
+});
+```
+
+### Чому це потрібно
+
+- **Виявлення локалі**: проміжне ПЗ `intlayer` обробляє вхідні запити для виявлення бажаної локалі користувача на основі заголовків, файлів cookie або інших налаштованих методів.
+- **Контекст перекладу**: налаштовує необхідний контекст для правильної роботи функції `t`, гарантуючи, що переклади повертаються правильною мовою.
+- **Запобігання помилкам**: без цього проміжного ПЗ використання функції `t` призведе до помилок під час виконання, оскільки необхідна інформація про локаль буде недоступна.
+
+---
+
+## Приклади використання
+
+### Базовий приклад
+
+Надавайте локалізований вміст різними мовами:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      uk: "Ласкаво просимо!",
+    })
+  );
+});
+```
+
+**Запити клієнтів:**
+
+- Клієнт із `Accept-Language: fr` отримає `Bienvenue!`.
+- Клієнт із `Accept-Language: uk` отримає `Ласкаво просимо!`.
+- Клієнт із `Accept-Language: de` отримає `Welcome!` (локаль за замовчуванням).
+
+### Обробка помилок
+
+Надавайте повідомлення про помилки кількома мовами:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/error", (c) => {
+  return c.text(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      uk: "Сталася неочікувана помилка.",
+    }),
+    500
+  );
+});
+```
+
+---
+
+### Використання варіантів локалі
+
+Укажіть переклади для конкретних варіантів локалей:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (c) => {
+  return c.text(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      uk: "Привіт!",
+    })
+  );
+});
+```
+
+---
+
+## Розширені теми
+
+### Механізм повернення (Fallback)
+
+Якщо бажана локаль недоступна, функція `t` повернеться до локалі за замовчуванням, визначеної в конфігурації:
+
+```typescript {5-6} fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.UKRAINIAN],
+    defaultLocale: Locales.ENGLISH,
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+---
+
+### Примусове використання суворого режиму
+
+Налаштуйте функцію `t` для забезпечення суворого дотримання оголошених локалей:
+
+| Режим       | Поведінка                                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| `strict`    | Для всіх оголошених локалей мають бути надані переклади. Відсутність локалей призведе до помилок.         |
+| `inclusive` | Оголошені локалі повинні мати переклади. Відсутність локалей викликає попередження, але вони приймаються. |
+| `loose`     | Приймається будь-яка існуюча локаль, навіть якщо вона не оголошена.                                       |
+
+---
+
+### Інтеграція з TypeScript
+
+Функція `t` є типобезпечною при використанні з TypeScript. Визначте типобезпечний об'єкт перекладів:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import { type LanguageContent } from "hono-intlayer";
+
+const translations: LanguageContent<string> = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  uk: "Доброго ранку!",
+};
+
+app.get("/morning", (c) => {
+  return c.text(t(translations));
+});
+```
+
+---
+
+### Поширені помилки та усунення несправностей
+
+| Проблема                       | Причина                              | Рішення                                                               |
+| ------------------------------ | ------------------------------------ | --------------------------------------------------------------------- |
+| Функція `t` не працює          | Проміжне ПЗ не завантажено           | Переконайтеся, що `app.use("*", intlayer())` додано перед маршрутами. |
+| Помилка відсутності перекладів | Увімкнено суворий режим без усіх мов | Надайте всі необхідні переклади.                                      |
+
+---
+
+## Висновок
+
+Функція `t` — це потужний інструмент для інтернаціоналізації бекенда. Ефективно використовуючи її, ви можете створити більш інклюзивний та зручний додаток для глобальної аудиторії. Для отримання інформації про розширене використання та детальні параметри конфігурації зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).