@intlayer/docs 9.3.3 → 9.4.0

package/docs/uk/intlayer_with_elysia.md

@@ -0,0 +1,343 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-24
+title: "Elysia i18n - Повний посібник щодо перекладу вашого додатка"
+description: "Більше ніяких i18next. Посібник 2026 року з розробки багатомовного (i18n) додатка Elysia. Перекладайте за допомогою AI агентів та оптимізуйте розмір bundle, SEO та продуктивність."
+keywords:
+  - Internationalization
+  - Documentation
+  - Intlayer
+  - Elysia
+  - JavaScript
+  - Backend
+slugs:
+  - doc
+  - environment
+  - elysia
+applicationTemplate: https://github.com/aymericzip/intlayer-elysia-template
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Узгодження посібника з шаблоном Elysia (типізація контексту, налаштування Bun, скрипти)"
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "init Elysia plugin"
+author: aymericzip
+---
+
+# Перекладіть свій Elysia backend веб-сайт за допомогою Intlayer | Інтернаціоналізація (i18n)
+
+`elysia-intlayer` – це потужний плагін інтернаціоналізації (i18n) для Elysia додатків, розроблений для того, щоб зробити ваші backend сервіси глобально доступними, надаючи локалізовані відповіді на основі переваг клієнта.
+
+> Див. реалізацію пакету на GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer
+
+### Практичні casos використання
+
+- **Відображення помилок Backend мовою користувача**: Коли виникає помилка, відображення повідомлень рідною мовою користувача покращує розуміння та зменшує розчарування. Це особливо корисно для динамічних повідомлень про помилки, які можуть відображатися в компонентах front-end, таких як toast-сповіщення або модальні вікна.
+- **Отримання багатомовного контенту**: Для додатків, які завантажують контент з бази даних, інтернаціоналізація забезпечує можливість подавати цей контент кількома мовами. Це критично важливо для платформ, таких як сайти електронної комерції або системи управління контентом, які повинні відображати описи продуктів, статті та інший контент мовою, яку переважає користувач.
+- **Надсилання багатомовних електронних листів**: Чи то трансакційні листи, маркетингові кампанії чи сповіщення, надсилання листів мовою одержувача може значно підвищити залучення та ефективність.
+- **Багатомовні push-сповіщення**: Для мобільних додатків надсилання push-сповіщень мовою, яку переважає користувач, може підвищити взаємодію та утримання користувачів. Цей особистісний підхід може зробити сповіщення більш релевантними та практичними.
+- **Інші комунікації**: Будь-яка форма комунікації з backend, така як SMS-повідомлення, системні сповіщення або оновлення користувацького інтерфейсу, виграють від того, що вони мовою користувача, забезпечуючи ясність та покращуючи загальний досвід користувача.
+
+Інтернаціоналізуючи backend, ваш додаток не лише поважає культурні відмінності, а й краще узгоджується з глобальними потребами ринку, що робить це ключовим кроком у масштабуванні ваших послуг по всьому світу.
+
+## Початок роботи
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-elysia-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Як інтернаціоналізувати вашу програму за допомогою Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+Див. [Application Template](https://github.com/aymericzip/intlayer-elysia-template) на GitHub.
+
+### Установка
+
+Щоб почати використовувати `elysia-intlayer`, встановіть пакет за допомогою npm:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive
+```
+
+> прапорець `--interactive` є опціональним. Використовуйте `intlayer-cli init`, якщо ви є AI-агентом.
+
+> Ця команда виявить ваше середовище та встановить необхідні пакети. Наприклад:
+
+```bash packageManager="npm"
+npm install intlayer elysia-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer elysia-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer elysia-intlayer
+```
+
+```bash packageManager="bun"
+bun add intlayer elysia-intlayer
+```
+
+> Elysia орієнтований на runtime **Bun**. `elysia-intlayer` спирається на `AsyncLocalStorage` (замість бібліотеки `cls-hooked`, яку використовують плагіни Intlayer на базі Node) саме тому, що Bun не реалізує `async_hooks.createHook`.
+
+### Налаштування
+
+Налаштуйте параметри інтернаціоналізації, створивши `intlayer.config.ts` у корені вашого проекту:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    /**
+     * Локаль за замовчуванням, яка використовується як fallback, якщо запитану локаль не знайдено.
+     */
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+### Оголосіть Ваш Контент
+
+Створюйте та керуйте своїми оголошеннями контенту для зберігання перекладів:
+
+```typescript fileName="src/index.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { t, type Dictionary } from "intlayer";
+
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      uk: "Приклад контенту, повернутого українською мовою",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      es: "Ejemplo de contenido devuelto en español",
+    }),
+  },
+} satisfies Dictionary;
+
+export default indexContent;
+```
+
+```json fileName="src/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "index",
+  "content": {
+    "exampleOfContent": {
+      "nodeType": "translation",
+      "translation": {
+        "uk": "Приклад контенту, повернутого українською мовою",
+        "en": "Example of returned content in English",
+        "fr": "Exemple de contenu renvoyé en français",
+        "es": "Ejemplo de contenido devuelto en español"
+      }
+    }
+  }
+}
+```
+
+> Ваші оголошення контенту можна визначити будь-де у вашому додатку, якщо вони включені в директорію `contentDir` (за замовчуванням `./src`). І відповідають розширенню файлу оголошення контенту (за замовчуванням `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`).
+
+> Для отримання додаткових інформацій зверніться до [документації оголошення контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md).
+
+### Налаштування додатка Elysia
+
+Налаштуйте ваш додаток Elysia для використання `elysia-intlayer`:
+
+```typescript fileName="src/index.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Elysia } from "elysia";
+import { intlayer } from "elysia-intlayer";
+
+const app = new Elysia()
+  // Завантажте плагін інтернаціоналізації
+  .use(intlayer())
+  // Маршрути
+  .get("/", ({ intlayer }) => ({
+    // Мова, яка використовується для цього запиту, узгоджена `Accept-Language` або прочитана з сховища
+    locale: intlayer!.locale,
+    greeting: intlayer!.t({
+      uk: "Привіт",
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    content: intlayer!.getIntlayer("index").exampleOfContent,
+  }))
+  .listen(3000);
+
+console.log(
+  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
+);
+```
+
+> Плагін реєструє свій контекст через **глобальний** `derive`, який Elysia типізує як `Partial<{ intlayer: IntlayerContext }>`. Під час виконання значення завжди присутнє для маршрутів, зареєстрованих після `.use(intlayer())`, тож використовуйте non-null assertion (`intlayer!.locale`) — або optional chaining — щоб задовольнити TypeScript у режимі `strict`.
+
+Контекст маршруту надає:
+
+| Властивість       | Опис                                                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `locale`          | Локаль, яку слід використати для цього запиту; `locale_storage` має пріоритет над `locale_detected`. |
+| `locale_storage`  | Локаль, явно запитана клієнтом через cookie або header.                                              |
+| `locale_detected` | Локаль, узгоджена із заголовків запиту.                                                              |
+| `defaultLocale`   | Локаль, налаштована як fallback у `intlayer.config.ts`.                                              |
+| `t`               | Функція перекладу.                                                                                   |
+| `getIntlayer`     | Функція для отримання словників за ключем.                                                           |
+| `getDictionary`   | Функція для обробки об'єктів словників.                                                              |
+
+Ті самі helpers також експортуються як standalone. Вони отримують поточний запит через `AsyncLocalStorage`, тож ви можете викликати їх без деструктуризації контексту:
+
+```typescript fileName="src/index.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Elysia } from "elysia";
+import { intlayer, t, getDictionary, getIntlayer } from "elysia-intlayer";
+import dictionaryExample from "./index.content";
+
+const app = new Elysia()
+  .use(intlayer())
+  .get("/t_example", () =>
+    t({
+      uk: "Приклад повернутого вмісту українською мовою",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      es: "Ejemplo de contenido devuelto en español",
+    })
+  )
+  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
+  .get(
+    "/getDictionary_example",
+    () => getDictionary(dictionaryExample).exampleOfContent
+  )
+  .listen(3000);
+```
+
+> Контекст запиту звільняється одразу після мапінгу відповіді, тож окремі хелпери ніколи не розв'язуються щодо вже завершеного запиту. Якщо їх викликати поза запитом, який обробляє плагін, вони повертаються до налаштованої локалі за замовчуванням.
+
+### Запуск вашого застосунку
+
+Додайте скрипти Intlayer до вашого `package.json`. `intlayer build` компілює ваші декларації контенту в директорію `.intlayer` і генерує типи TypeScript:
+
+```json fileName="package.json"
+{
+  "scripts": {
+    "dev": "intlayer build && bun run --watch src/index.ts",
+    "build": "intlayer build",
+    "start": "bun run src/index.ts",
+    "i18n:fill": "intlayer fill",
+    "i18n:test": "intlayer test"
+  }
+}
+```
+
+Потім запустіть сервер:
+
+```bash
+bun run dev
+```
+
+Перевірте узгодження локалі за допомогою `Accept-Language`:
+
+```bash
+curl -H "Accept-Language: fr" http://localhost:3000/
+# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}
+
+curl -H "Accept-Language: es" http://localhost:3000/
+# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}
+```
+
+> `intlayer build` не є суворо обов'язковим перед `bun run src/index.ts`: плагін також готує словники під час старту застосунку Elysia. Запуск наперед тримає згенеровані типи актуальними для вашого редактора та усуває вартість збірки під час першого запиту.
+
+### Сумісність
+
+`elysia-intlayer` повністю сумісна з:
+
+- [`react-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/index.md) для React додатків
+- [`next-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/next-intlayer/index.md) для Next.js додатків
+- [`vite-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vite-intlayer/index.md) для Vite додатків
+
+Вона також безперебійно працює з будь-яким рішенням для інтернаціоналізації в різних середовищах, включаючи браузери та API запити.
+
+За замовчуванням плагін визначає локаль у такому порядку:
+
+1. Cookie `INTLAYER_LOCALE`.
+2. Заголовок `x-intlayer-locale`.
+3. Узгодження через заголовок `Accept-Language`.
+
+Ви можете налаштувати cookie та заголовок, які використовуються для визначення локалі:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Інші параметри конфігурації
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
+  },
+};
+
+export default config;
+```
+
+> Для отримання додаткової інформації про конфігурацію та розширені теми відвідайте нашу [документацію](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md).
+
+### Налаштування TypeScript
+
+`elysia-intlayer` використовує надійні можливості TypeScript для покращення процесу локалізації. Статична типізація TypeScript забезпечує, що кожен ключ перекладу враховується, зменшуючи ризик пропущених перекладів і покращуючи maintainability.
+
+Переконайтеся, що автоматично створені типи (за замовчуванням у ./types/intlayer.d.ts) включені у ваш файл tsconfig.json.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Ваші існуючі конфігурації TypeScript
+  "include": [
+    // ... Ваші існуючі конфігурації TypeScript
+    ".intlayer/**/*.ts", // Включити автоматично створені типи
+  ],
+}
+```
+
+### VS Code Extension
+
+Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне **розширення Intlayer для VS Code**.
+
+[Встановити з VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+Це розширення надає:
+
+- **Автодоповнення** для ключів перекладу.
+- **Виявлення помилок в реальному часі** для відсутніх перекладів.
+- **Вбудовані попередні перегляди** перекладеного вмісту.
+- **Швидкі дії** для легкого створення та оновлення перекладів.
+
+Для більш детальної інформації про використання розширення звертайтесь до [документації розширення Intlayer VS Code Extension](https://intlayer.org/doc/vs-code-extension).
+
+### Конфігурація Git
+
+Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволяє уникнути їх комітування в ваш Git-репозиторій.
+
+Щоб це зробити, ви можете додати наступні інструкції до вашого файлу `.gitignore`:
+
+```plaintext fileName=".gitignore"
+# Ігнорувати файли, згенеровані Intlayer
+.intlayer
+```

package/docs/uk/intlayer_with_express.md

@@ -220,9 +220,11 @@ import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   // ... Інші параметри конфігурації
-  middleware: {
-    headerName: "my-locale-header",
-    cookieName: "my-locale-cookie",
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
   },
 };
 

package/docs/uk/intlayer_with_fastify.md

@@ -222,9 +222,11 @@ import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   // ... Інші параметри налаштування
-  middleware: {
-    headerName: "my-locale-header",
-    cookieName: "my-locale-cookie",
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
   },
 };
 

package/docs/uk/intlayer_with_hono.md

@@ -142,6 +142,45 @@ const indexContent = {
 export default indexContent;
 ```
 
+```javascript fileName="src/index.content.cjs" codeFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      uk: "Приклад повернутого вмісту українською мовою",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    }),
+  },
+};
+
+module.exports = indexContent;
+```
+
+```json fileName="src/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "index",
+  "content": {
+    "exampleOfContent": {
+      "nodeType": "translation",
+      "translation": {
+        "uk": "Приклад повернутого вмісту українською мовою",
+        "en": "Example of returned content in English",
+        "fr": "Exemple de contenu renvoyé en français",
+        "es-ES": "Ejemplo de contenido devuelto en español (España)",
+        "es-MX": "Ejemplo de contenido devuelto en español (México)"
+      }
+    }
+  }
+}
+```
+
 > Ваші оголошення вмісту можуть бути визначені в будь-якому місці вашого додатка, якщо вони включені в каталог `contentDir` (за замовчуванням `./src`) і відповідають розширенню файлу оголошення вмісту (за замовчуванням `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`).
 
 > Для отримання додаткової інформації зверніться до [документації з оголошення вмісту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md).
@@ -197,9 +236,11 @@ import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   // ... Інші параметри конфігурації
-  middleware: {
-    headerName: "my-locale-header",
-    cookieName: "my-locale-cookie",
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
   },
 };
 

package/docs/uk/intlayer_with_lynx+react.md

@@ -67,7 +67,7 @@ Intlayer оптимізовано для ідеальної роботи з Lynx
 
 <Accordion header="Агент AI">
 
-Спільне розміщення вмісту **зменшує контекст, необхідний** для великих мовних моделей (LLM). Intlayer також постачається з набором інструментів, наприклад **CLI** для перевірки відсутніх перекладів,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** і **[навички агента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, щоб зробити роботу розробника (DX) ще зручнішою для агентів ШІ.
+Спільне розміщення вмісту **зменшує контекст, необхідний** для великих мовних моделей (LLM). Intlayer також постачається з набором інструментів, наприклад **CLI** для перевірки відсутніх перекладів,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** і **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/agent_skills.md)**, щоб зробити роботу розробника (DX) ще зручнішою для агентів ШІ.
 
 </Accordion>
 
@@ -145,8 +145,6 @@ bun add intlayer react-intlayer lynx-intlayer
 - **lynx-intlayer**  
   Інтеграція для Lynx, яка надає плагін для інтеграції Intlayer з бандлером Lynx.
 
-///
-
 ---
 
 </Step>

package/docs/uk/intlayer_with_nestjs.md

@@ -205,9 +205,11 @@ import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   // ... Other configuration options
-  middleware: {
-    headerName: "my-locale-header",
-    cookieName: "my-locale-cookie",
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
   },
 };