@intlayer/docs 8.0.0 → 8.0.1-canary.1

package/docs/ru/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` предоставляет промежуточное ПО (middleware) для приложений 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/ru/packages/adonis-intlayer/intlayer.md) |
+
+### Функции
+
+| Функция         | Описание                                                                                                                                                                                                                    | Связанная документация                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `t`             | Функция перевода, которая извлекает контент для текущей локали. Работает в рамках жизненного цикла запроса, управляемого промежуточным ПО `intlayer`. Использует CLS (Async Local Storage) для доступа к контексту запроса. | [перевод](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/translation.md) |
+| `getIntlayer`   | Извлекает словарь по его ключу из сгенерированного объявления и возвращает его содержимое для указанной локали. Оптимизированная версия `getDictionary`. Использует CLS для доступа к контексту запроса.                    | -                                                                                                  |
+| `getDictionary` | Обрабатывает объекты словаря и возвращает контент для указанной локали. Обрабатывает переводы `t()`, перечисления, markdown, HTML и т. д. Использует CLS для доступа к контексту запроса.                                   | -                                                                                                  |
+| `getLocale`     | Извлекает текущую локаль из контекста запроса с помощью CLS.                                                                                                                                                                | -                                                                                                  |

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

@@ -0,0 +1,54 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Документация промежуточного ПО AdonisJS Intlayer | 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: Начальная документация
+---
+
+# Документация промежуточного ПО AdonisJS Intlayer
+
+Промежуточное ПО `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/ru/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/ru/configuration.md).

package/docs/ru/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/ru/packages/hono-intlayer/intlayer.md) |
+
+### Функции
+
+Импорт:
+
+```tsx
+import { t, getIntlayer, getDictionary } from "hono-intlayer";
+```
+
+| Функция         | Описание                                                                                                                                                                                                                                    | Ссылка на док.                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Глобальная функция перевода, которая извлекает контент для текущей локали в Hono. Использует CLS (Async Local Storage) и должна использоваться в контексте запроса, управляемом промежуточным ПО `intlayer`. Также доступна через контекст. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/translation.md) |
+| `getIntlayer`   | Извлекает словарь по его ключу из сгенерированной декларации и возвращает его содержимое для указанной локали. Оптимизированная версия `getDictionary`. Использует CLS для доступа к контексту запроса. Также доступна через контекст.      | -                                                                                                      |
+| `getDictionary` | Обрабатывает объекты словаря и возвращает содержимое для указанной локали. Обрабатывает переводы `t()`, перечисления, markdown, HTML и т. д. Использует CLS для доступа к контексту запроса. Также доступна через контекст.                 | -                                                                                                      |

package/docs/ru/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",
+    ru: "Привет",
+  });
+
+  return c.text(content);
+});
+```
+
+## Описание
+
+Промежуточное ПО выполняет следующие задачи:
+
+1. **Определение локали**: анализирует запрос (заголовки, cookies и т. д.) для определения предпочтительной локали пользователя.
+2. **Заполнение контекста**: добавляет данные Intlayer в контекст Hono, доступный через `c.get()`. Сюда входят:
+   - `locale`: определенная локаль.
+   - `t`: функция перевода.
+   - `getIntlayer`: функция для получения словарей.
+   - `getDictionary`: функция для обработки объектов словаря.
+3. **Управление контекстом**: использует `cls-hooked` для управления асинхронным контекстом, позволяя глобальным функциям Intlayer (`t`, `getIntlayer`, `getDictionary`) получать доступ к локали, специфичной для запроса, без передачи объекта контекста.

package/docs/ru/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`, `ru`), а значения — соответствующие переведенные строки.
+
+### Возвращаемое значение
+
+- Строка, представляющая контент на предпочтительном языке клиента.
+
+---
+
+## Загрузка обработчика запросов интернационализации
+
+Чтобы обеспечить корректную работу функций интернационализации, предоставляемых `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!",
+      ru: "Привет, мир!",
+    })
+  );
+});
+```
+
+```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!",
+      ru: "Привет, мир!",
+    })
+  );
+});
+```
+
+```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!",
+      ru: "Привет, мир!",
+    })
+  );
+});
+```
+
+### Почему это необходимо
+
+- **Определение локали**: промежуточное ПО `intlayer` обрабатывает входящие запросы для определения предпочтительной локали пользователя на основе заголовков, файлов cookie или других настроенных методов.
+- **Контекст перевода**: настраивает необходимый контекст для правильной работы функции `t`, гарантируя, что переводы возвращаются на правильном языке.
+- **Предотвращение ошибок**: без этого промежуточного ПО использование функции `t` приведет к ошибкам во время выполнения, так как необходимая информация о локали будет недоступна.
+
+---
+
+## Примеры использования
+
+### Базовый пример
+
+Предоставление локализованного контента на разных языках:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      ru: "Добро пожаловать!",
+    })
+  );
+});
+```
+
+**Запросы клиентов:**
+
+- Клиент с `Accept-Language: fr` получит `Bienvenue!`.
+- Клиент с `Accept-Language: ru` получит `Добро пожаловать!`.
+- Клиент с `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.",
+      ru: "Произошла непредвиденная ошибка.",
+    }),
+    500
+  );
+});
+```
+
+---
+
+### Использование вариантов локали
+
+Укажите переводы для конкретных вариантов локалей:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (c) => {
+  return c.text(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      ru: "Привет!",
+    })
+  );
+});
+```
+
+---
+
+## Расширенные темы
+
+### Механизм возврата (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.RUSSIAN],
+    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!",
+  ru: "Доброе утро!",
+};
+
+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).