@intlayer/docs 7.5.11 → 7.5.13

package/docs/uk/bundle_optimization.md

@@ -0,0 +1,185 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: Оптимізація розміру бандла та продуктивності i18n
+description: Зменшіть розмір бандла застосунку, оптимізуючи контент інтернаціоналізації (i18n). Дізнайтесь, як використовувати tree shaking та lazy loading для словників з Intlayer.
+keywords:
+  - Оптимізація bundle
+  - Автоматизація контенту
+  - Динамічний контент
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: Init history
+---
+
+# Оптимізація розміру бандла та продуктивності i18n
+
+Одна з найпоширеніших проблем традиційних i18n-рішень, що базуються на JSON-файлах — це керування розміром контенту. Якщо розробники не розділяють контент вручну по неймспейсах, користувачі часто в кінцевому підсумку завантажують переклади для всіх сторінок і, можливо, для всіх мов лише для перегляду однієї сторінки.
+
+Наприклад, застосунок з 10 сторінками, перекладеними на 10 мов, може призвести до того, що користувач завантажує контент 100 сторінок, хоча йому потрібна лише **одна** (поточна сторінка поточною мовою). Це призводить до марної витрати трафіку та повільнішого завантаження.
+
+> Щоб виявити це, ви можете використовувати аналізатор бандлу, такий як `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) або `webpack-bundle-analyzer` (React CRA / Angular / тощо).
+
+**Intlayer вирішує цю проблему через оптимізацію під час збірки.** Він аналізує ваш код, щоб визначити, які словники фактично використовуються для кожного компонента, і повторно вбудовує в бандл лише необхідний вміст.
+
+## Зміст
+
+<TOC />
+
+## Як це працює
+
+Intlayer використовує **підхід на рівні компонентів**. На відміну від глобальних JSON-файлів, ваш вміст визначається поруч із компонентами або всередині них. Під час процесу збірки Intlayer:
+
+1.  **Аналізує** ваш код, щоб знайти виклики `useIntlayer`.
+2.  **Формує** відповідний вміст словників.
+3.  **Замінює** виклик `useIntlayer` на оптимізований код відповідно до вашої конфігурації.
+
+Це гарантує, що:
+
+- Якщо компонент не імпортується, його вміст не включається до бандла (видалення мертвого коду — Dead Code Elimination).
+- Якщо компонент завантажується lazy-loaded, його вміст також завантажується lazy-loaded.
+
+## Налаштування за платформою
+
+### Next.js
+
+Next.js вимагає плагін `@intlayer/swc` для обробки трансформації, оскільки Next.js використовує SWC для збірок.
+
+> Цей плагін встановлено за замовчуванням, оскільки SWC-плагіни досі експериментальні для Next.js. Це може змінитися в майбутньому.
+
+### Vite
+
+Vite використовує плагін `@intlayer/babel`, який включений як залежність `vite-intlayer`. Оптимізація увімкнена за замовчуванням.
+
+### Webpack
+
+Щоб увімкнути оптимізацію бандла з Intlayer на Webpack, потрібно встановити та налаштувати відповідний плагін Babel (`@intlayer/babel`) або SWC (`@intlayer/swc`).
+
+### Expo / Lynx
+
+Оптимізація бандла **ще недоступна** для цієї платформи. Підтримка буде додана в майбутньому релізі.
+
+## Конфігурація
+
+Ви можете контролювати, як Intlayer оптимізує ваш бандл через властивість `build` у файлі `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // або 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> У більшості випадків рекомендовано залишати опцію `optimize` за замовчуванням.
+
+> Див. документацію з конфігурації для більш детальної інформації: [Конфігурація](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)
+
+### Параметри збірки
+
+Наступні параметри доступні в об'єкті конфігурації `build`:
+
+| Властивість           | Тип                             | Значення за замовчуванням       | Опис                                                                                                                                                                                                              |
+| :-------------------- | :------------------------------ | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | Керує тим, чи увімкнена оптимізація під час збірки. Якщо `true`, Intlayer замінює виклики словників на оптимізовані інжекти. Якщо `false`, оптимізація вимкнена. Рекомендовано встановлювати `true` у production. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Визначає, як завантажуються словники (див. деталі нижче).                                                                                                                                                         |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Glob-шаблони, що визначають, які файли Intlayer має сканувати для оптимізації. Використовуйте це, щоб виключати несуміжні файли та прискорити збірку.                                                             |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Керує форматом згенерованих словників.                                                                                                                                                                            |
+
+## Режими імпорту
+
+Налаштування `importMode` визначає, як вміст словника вставляється у ваш компонент.
+
+### 1. Статичний режим (`default`)
+
+У статичному режимі Intlayer замінює `useIntlayer` на `useDictionary` і вбудовує словник безпосередньо в JavaScript-бандл.
+
+- **Переваги:** Миттєвий рендеринг (синхронно), відсутність додаткових мережевих запитів під час гідратації.
+- **Недоліки:** Бандл містить переклади для **усіх** доступних мов для цього конкретного компонента.
+- **Найкраще для:** односторінкових додатків (SPA).
+
+**Приклад трансформованого коду:**
+
+```tsx
+// Ваш код
+const content = useIntlayer("my-key");
+
+// Оптимізований код (Статичний)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      uk: "Мій заголовок",
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. Динамічний режим
+
+У динамічному режимі Intlayer замінює `useIntlayer` на `useDictionaryAsync`. Це використовує `import()` (механізм, схожий на Suspense) для лінивого підвантаження саме JSON для поточної локалі.
+
+- **Плюси:** **Tree-shaking на рівні локалі.** Користувач, який переглядає англійську версію, завантажить _лише_ англійський словник. Французький словник ніколи не завантажується.
+- **Мінуси:** Під час гідратації ініціюється мережевий запит (завантаження ресурсу) для кожного компонента.
+- **Кращий вибір для:** Великих текстових блоків, статей або застосунків з підтримкою багатьох мов, де розмір бандла критично важливий.
+
+**Приклад трансформованого коду:**
+
+```tsx
+// Ваш код
+const content = useIntlayer("my-key");
+
+// Оптимізований код (Динамічний)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
+      (mod) => mod.default
+    ),
+});
+```
+
+> Коли ви використовуєте `importMode: 'dynamic'`, якщо на одній сторінці 100 компонентів використовують `useIntlayer`, браузер спробує виконати 100 окремих запитів. Щоб уникнути цього «водоспаду» запитів, групуйте контент у меншу кількість `.content` файлів (наприклад, по одному словнику на секцію сторінки), замість одного файлу на кожен атом-компонент.
+
+> Наразі `importMode: 'dynamic'` не повністю підтримується для Vue та Svelte. Рекомендується використовувати `importMode: 'static'` для цих фреймворків до наступних оновлень.
+
+### 3. Живий режим
+
+Працює аналогічно динамічному режиму, але спочатку намагається отримати словники з Intlayer Live Sync API. Якщо виклик API не вдасться або вміст не позначено для живих оновлень, виконується відкат до динамічного імпорту.
+
+> Див. документацію CMS для детальнішої інформації: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md)
+
+## Підсумок: Статичний vs Динамічний
+
+| Особливість                | Статичний режим                           | Динамічний режим                                |
+| :------------------------- | :---------------------------------------- | :---------------------------------------------- |
+| **Розмір JS-бандла**       | Більший (включає всі мови для компонента) | Найменший (тільки код, без контенту)            |
+| **Початкове завантаження** | Миттєво (вміст у bundle)                  | Невелика затримка (завантажує JSON)             |
+| **Мережеві запити**        | 0 додаткових запитів                      | 1 запит на словник                              |
+| **Tree Shaking**           | На рівні компонентів                      | На рівні компонентів + на рівні локалі          |
+| **Найкраще використання**  | UI Components, невеликі додатки           | Сторінки з великою кількістю тексту, багато мов |

package/docs/uk/cli/build.md

@@ -0,0 +1,64 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Побудова словників
+description: Дізнайтеся, як побудувати словники Intlayer зі файлів декларації контенту.
+keywords:
+  - Build
+  - Dictionaries
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - build
+---
+
+# Побудова словників
+
+Щоб побудувати ваші словники, ви можете виконати команди:
+
+```bash
+npx intlayer build
+```
+
+або в режимі відстеження
+
+```bash
+npx intlayer build --watch
+```
+
+Ця команда за замовчуванням знайде ваші файли декларації контенту за шляхом `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}` і побудує словники в директорії `.intlayer`.
+
+## Аліаси:
+
+- `npx intlayer dictionaries build`
+- `npx intlayer dictionary build`
+- `npx intlayer dic build`
+
+## Аргументи:
+
+- **`--base-dir`**: Вказати базовий каталог проєкту. Щоб знайти конфігурацію intlayer, команда шукатиме файл `intlayer.config.{ts,js,json,cjs,mjs}` у базовому каталозі.
+
+  > Приклад: `npx intlayer build --base-dir ./src`
+
+- **`--env`**: Вказати середовище (наприклад, `development`, `production`). Корисно, якщо ви використовуєте змінні середовища в файлі конфігурації intlayer.
+
+  > Приклад: `npx intlayer build --env production`
+
+- **`--env-file`**: Вказати кастомний файл середовища, звідки завантажувати змінні. Корисно, якщо ви використовуєте змінні середовища в файлі конфігурації intlayer.
+
+  > Приклад: `npx intlayer build --env-file .env.production.local`
+
+- **`--with`**: Запустити команду паралельно зі збіркою.
+
+  > Приклад: `npx intlayer build --with "next dev --turbopack"`
+
+- **`--skip-prepare`**: Пропустити крок підготовки.
+
+  > Приклад: `npx intlayer build --skip-prepare`
+
+- **`--no-cache`**: Вимкнути кеш.
+
+  > Приклад: `npx intlayer build --no-cache`

package/docs/uk/cli/ci.md

@@ -0,0 +1,137 @@
+---
+createdAt: 2026-01-06
+updatedAt: 2026-01-06
+title: Команда CI
+description: Дізнайтеся, як використовувати команду Intlayer CI для запуску команд Intlayer з автоматично підставленими обліковими даними у CI/CD пайплайнах та монорепозиторіях.
+keywords:
+  - CI
+  - CI/CD
+  - Automation
+  - Monorepo
+  - Credentials
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - ci
+history:
+  - version: 7.5.11
+    date: 2026-01-06
+    changes: Додано команду CI
+---
+
+# Команда CI
+
+```bash
+npx intlayer ci <command...>
+```
+
+Команда CI призначена для автоматизації та CI/CD-пайплайнів. Вона автоматично підставляє облікові дані зі змінної оточення `INTLAYER_PROJECT_CREDENTIALS` і може виконувати команди Intlayer для кількох проєктів у монорепозиторії.
+
+## Як це працює
+
+Команда CI працює в двох режимах:
+
+1. **Режим одного проєкту**: Якщо поточний робочий каталог відповідає одному зі шляхів проєктів у `INTLAYER_PROJECT_CREDENTIALS`, команда запускається лише для цього конкретного проєкту.
+
+2. **Режим ітерації**: Якщо контекст конкретного проєкту не виявлено, вона перебирає всі налаштовані проєкти й виконує команду для кожного з них.
+
+## Змінна середовища
+
+Команда вимагає встановленої змінної середовища `INTLAYER_PROJECT_CREDENTIALS`. Ця змінна повинна містити JSON-обʼєкт, який відображає шляхи проєктів на їхні облікові дані:
+
+```json
+{
+  "packages/app": {
+    "clientId": "your-client-id-1",
+    "clientSecret": "your-client-secret-1"
+  },
+  "packages/admin": {
+    "clientId": "your-client-id-2",
+    "clientSecret": "your-client-secret-2"
+  }
+}
+```
+
+## Визначення менеджера пакетів
+
+Команда CI автоматично визначає, який package manager використовується (npm, yarn, pnpm або bun) на основі змінної середовища `npm_config_user_agent` і використовує відповідну команду для запуску Intlayer.
+
+## Аргументи
+
+- **`<command...>`**: Команда Intlayer для виконання (наприклад, `fill`, `push`, `build`). Ви можете передати будь-яку команду Intlayer та її аргументи.
+
+  > Приклад: `npx intlayer ci fill --verbose`
+  >
+  > Приклад: `npx intlayer ci push`
+  >
+  > Приклад: `npx intlayer ci build`
+
+## Приклади
+
+### Запустити команду в режимі одного проекту
+
+Якщо ви перебуваєте в директорії проекту, що відповідає одному з шляхів у `INTLAYER_PROJECT_CREDENTIALS`:
+
+```bash
+cd packages/app
+npx intlayer ci fill
+```
+
+Це запустить команду `fill` з автоматично підставленими обліковими даними для проєкту `packages/app`.
+
+### Запустити команду для всіх проєктів
+
+Якщо ви перебуваєте в каталозі, який не відповідає жодному шляху проєкту, команда пройде по всіх налаштованих проєктах:
+
+```bash
+cd /path/to/monorepo
+npx intlayer ci push
+```
+
+Це виконає команду `push` для кожного проєкту, налаштованого в `INTLAYER_PROJECT_CREDENTIALS`.
+
+### Передача додаткових прапорів
+
+Ви можете передати будь-які прапори в базову команду Intlayer:
+
+```bash
+npx intlayer ci fill --verbose --mode complete
+```
+
+### Використання в CI/CD пайплайнах
+
+У вашій конфігурації CI/CD (наприклад, GitHub Actions, GitLab CI) встановіть `INTLAYER_PROJECT_CREDENTIALS` як секрет:
+
+```yaml
+# Приклад GitHub Actions
+env:
+  INTLAYER_PROJECT_CREDENTIALS: ${{ secrets.INTLAYER_PROJECT_CREDENTIALS }}
+
+steps:
+  - name: Fill dictionaries
+    run: npx intlayer ci fill
+```
+
+## Обробка помилок
+
+- Якщо `INTLAYER_PROJECT_CREDENTIALS` не встановлено, команда завершиться з помилкою.
+- Якщо `INTLAYER_PROJECT_CREDENTIALS` не є валідним JSON, команда завершиться з помилкою.
+- Якщо шлях до проекту не існує, він буде пропущений з попередженням.
+- Якщо будь-який проект зазнає невдачі, команда завершиться з кодом стану, відмінним від нуля.
+
+## Випадки використання
+
+- **Автоматизація монорепо**: Виконувати команди Intlayer для кількох проектів у монорепозиторії
+- **Конвеєри CI/CD**: Автоматизувати керування словниками в процесах безперервної інтеграції
+- **Масові операції**: Виконувати одну й ту саму операцію одночасно для кількох проектів Intlayer
+- **Управління секретами**: Безпечно керуйте обліковими даними для кількох проєктів за допомогою змінних середовища
+
+## Кращі практики безпеки
+
+- Зберігайте `INTLAYER_PROJECT_CREDENTIALS` як зашифровані секрети на вашій платформі CI/CD
+- Ніколи не комітіть облікові дані у систему контролю версій
+- Використовуйте окремі облікові дані для різних середовищ розгортання
+- Регулярно проводьте ротацію облікових даних

package/docs/uk/cli/configuration.md

@@ -0,0 +1,63 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Керування конфігурацією
+description: Дізнайтеся, як отримувати та завантажувати вашу конфігурацію Intlayer у CMS.
+keywords:
+  - Конфігурація
+  - Налаштування
+  - CLI
+  - Intlayer
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - configuration
+---
+
+# Керування конфігурацією
+
+## Отримати конфігурацію
+
+Команда `configuration get` отримує поточну конфігурацію для Intlayer, зокрема налаштування локалі. Це корисно для перевірки вашої установки.
+
+```bash
+npx intlayer configuration get
+```
+
+## Аліаси:
+
+- `npx intlayer config get`
+- `npx intlayer conf get`
+
+## Аргументи:
+
+- **`--env`**: Вкажіть середовище (наприклад, `development`, `production`).
+- **`--env-file`**: Надайте власний файл середовища для завантаження змінних.
+- **`--base-dir`**: Вказати базовий каталог проекту.
+- **`--verbose`**: Увімкнути детальне логування для відлагодження. (за замовчуванням true при використанні CLI)
+- **`--no-cache`**: Вимкнути кеш.
+
+## Надіслати конфігурацію
+
+Команда `configuration push` завантажує вашу конфігурацію в Intlayer CMS та редактор. Цей крок необхідний для увімкнення використання віддалених словників в Intlayer Visual Editor.
+
+```bash
+npx intlayer configuration push
+```
+
+## Аліаси:
+
+- `npx intlayer config push`
+- `npx intlayer conf push`
+
+## Аргументи:
+
+- **`--env`**: Вказати середовище (наприклад, `development`, `production`).
+- **`--env-file`**: Надати власний файл середовища для завантаження змінних.
+- **`--base-dir`**: Вказати базовий каталог проекту.
+- **`--verbose`**: Увімкнути детальне логування для налагодження. (за замовчуванням true при використанні CLI)
+- **`--no-cache`**: Вимкнути кеш.
+
+Після пушу конфігурації ваш проєкт повністю інтегрується з Intlayer CMS, що дозволяє безшовне керування словниками між командами.

package/docs/uk/cli/debug.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Налагодження команди Intlayer
+description: Дізнайтеся, як налагоджувати та усувати неполадки в Intlayer CLI.
+keywords:
+  - Налагодження
+  - Усунення неполадок
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - debug
+---
+
+# Налагодження команди Intlayer
+
+## 1. **Переконайтеся, що ви використовуєте останню версію**
+
+Виконайте:
+
+```bash
+npx intlayer --version                  # поточна локальна версія intlayer
+npx intlayer@latest --version           # остання доступна версія intlayer
+```
+
+## 2. **Перевірте, чи команда зареєстрована**
+
+Перевірити можна за допомогою:
+
+```bash
+npx intlayer --help                     # Показує список доступних команд та інформацію про використання
+npx intlayer dictionary build --help    # Показує список доступних опцій для команди
+```
+
+## 3. **Перезапустіть термінал**
+
+Іноді потрібно перезапустити термінал, щоб він розпізнав нові команди.
+
+## 4. **Очистіть кеш npx (якщо ви застрягли на старішій версії)**
+
+```bash
+npx clear-npx-cache
+```

package/docs/uk/cli/doc-review.md

@@ -0,0 +1,43 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Перевірка документа
+description: Дізнайтеся, як перевіряти файли документації на предмет якості, узгодженості та повноти для різних локалей.
+keywords:
+  - Перевірка
+  - Документ
+  - Документація
+  - AI
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - doc-review
+---
+
+# Перевірка документа
+
+Команда `doc review` аналізує файли документації на предмет якості, узгодженості та повноти в різних локалях.
+
+```bash
+npx intlayer doc review
+```
+
+Її можна використовувати для перевірки файлів, які вже перекладені, а також для оцінки коректності перекладу.
+
+У більшості випадків,
+
+- віддавайте перевагу використанню `doc translate` коли перекладена версія цього файлу недоступна.
+- надавайте перевагу використанню `doc review`, коли перекладена версія цього файлу вже існує.
+
+> Зауважте, що процес рев'ю споживає більше вхідних токенів, ніж процес перекладу для повного перегляду того самого файлу. Проте процес рев'ю оптимізує chunks для перегляду і пропускатиме ті частини, які не були змінені.
+
+## Аргументи:
+
+Команда `doc review` приймає ті самі аргументи, що й `doc translate`, що дозволяє переглядати конкретні документаційні файли та застосовувати перевірки якості.
+
+Якщо ви активували одну з опцій git, команда перегляне лише ту частину файлів, яка була змінена. Скрипт обробляє файл, розбиваючи його на chunks, і перевіряє кожен chunk. Якщо в chunk немає змін, скрипт пропустить його, щоб пришвидшити процес рев'ю та зменшити витрати на API постачальника AI.
+
+Для повного переліку аргументів див. документацію команди [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/doc-translate.md).