@intlayer/docs 7.5.12 → 7.5.14

package/docs/uk/autoFill.md

@@ -0,0 +1,307 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-09-20
+title: Автозаповнення
+description: Дізнайтеся, як використовувати функцію автозаповнення в Intlayer для автоматичного заповнення контенту на основі заздалегідь визначених шаблонів. Дотримуйтесь цієї документації, щоб ефективно реалізувати можливості автозаповнення у вашому проєкті.
+keywords:
+  - Автозаповнення
+  - Автоматизація контенту
+  - Динамічний контент
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - auto-fill
+history:
+  - version: 7.0.0
+    date: 2025-10-23
+    changes: Перейменовано `autoFill` на `fill` та оновлено поведінку
+  - version: 6.0.0
+    date: 2025-09-20
+    changes: Додано глобальну конфігурацію
+  - version: 6.0.0
+    date: 2025-09-17
+    changes: Додано змінну `{{fileName}}`
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізовано історію
+---
+
+# Заповнення файлів декларації контенту
+
+**Файли декларації контенту з автозаповненням** у вашому CI — це спосіб прискорити робочий процес розробки.
+
+## Розуміння поведінки
+
+Команда `fill` має два режими:
+
+- **Complete**: Автоматично заповнює весь відсутній контент для кожної локалі та редагує поточний файл або інший файл, якщо вказано. Тобто режим Complete пропускає переклад наявного контенту, якщо він уже перекладений.
+- **Review**: Автоматично заповнює **весь** контент для кожної локалі та генерує файл для поточного або вказаного іншого файлу.
+
+Команда `fill` обробляє лише ваші локальні файли декларації контенту. Тобто вона не обробляє віддалений контент із CMS — CMS має власну систему керування перекладами.
+Якщо ви використовуєте плагіни, такі як `@intlayer/sync-json-plugin`, Intlayer перетворить JSON-файли на файли декларацій локалізованого контенту. Тобто вони будуть оброблятися командою `fill`.
+
+У новостворених файлах міститься інструкція `filled` як метадані словника. Ця інструкція використовується Intlayer, щоб визначити, чи файл був автозаповнений, і, якщо так, пропустити цей файл при наступному перекладі.
+
+Intlayer також враховуватиме такі інструкції для автозаповнення:
+
+- Із вашого файлу `.content.{ts|js|json}` → інструкція `fill`
+- Із конфігураційного файлу `.intlayer.config.ts` → інструкція `dictionary.fill`
+- Якщо ніде не вказано — за замовчуванням буде встановлено `true`
+
+Для деклараційних файлів вмісту, що призначені для окремої локалі (per-locale), інструкція `true` буде замінена на `./{{fileName}}.fill.content.json`. Це відбувається тому, що такий per-locale деклараційний файл вмісту не може отримувати додатковий локалізований вміст. Отже, буде згенеровано новий файл, щоб не перезаписувати існуючий файл.
+
+## Поведінка за замовчуванням
+
+За замовчуванням глобальний параметр `fill` встановлено в `true`, що означає, що Intlayer автоматично заповнюватиме всі файли вмісту та редагуватиме сам файл. Цю поведінку можна налаштувати кількома способами:
+
+### Глобальні параметри конфігурації
+
+1. **`fill: true` (default)** - Автоматично заповнювати всі локалі та редагувати поточний файл
+2. **`fill: false`** - Вимкнути автоматичне заповнення для цього файлу вмісту
+3. **`fill: "./relative/path/to/file"`** - Створює/оновлює вказаний файл без редагування поточного, вказуючи на відносний шлях, який резольвується на основі розташування поточного файлу
+4. **`fill: "/absolute/path/to/file"`** - Створює/оновлює вказаний файл без редагування поточного, вказуючи шлях, що резольвується відносно базового каталогу (поле `baseDir` у файлі конфігурації `.intlayer.config.ts`)
+5. **`fill: "C:\\absolute\path\to\file"`** - Створює/оновлює вказаний файл без редагування поточного, вказуючи на абсолютний шлях, який резольвується на основі вашої операційної системи
+6. **`fill: { [key in Locales]?: string }`** - Створює/оновлює вказаний файл для кожної локалі
+
+### Зміни поведінки у v7
+
+У версії v7 поведінка команди `fill` була оновлена:
+
+- **`fill: true`** - Перезаписує поточний файл із заповненим вмістом для всіх локалей
+- **`fill: "path/to/file"`** - Заповнює вказаний файл, не змінюючи поточний файл
+- **`fill: false`** - Повністю відключає автоматичне заповнення
+
+При використанні опції шляху для запису в інший файл механізм fill працює через _master-slave_ зв'язок між файлами декларацій вмісту. Основний (master) файл є джерелом істини, і коли він оновлюється, Intlayer автоматично застосовує ці зміни до похідних (filled) файлів декларацій, вказаних у шляху.
+
+### Налаштування для кожної локалі
+
+Ви також можете налаштувати поведінку для кожної локалі, використовуючи об'єкт:
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Рекомендовано, щоб уникнути помилки Property 'pl' is missing in type '{ en: string; xxx } on your t function if
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Заповнює та редагує поточний файл для англійської
+      fr: "./translations/fr.json", // Створює окремий файл для французької
+      es: false, // Вимикає заповнення для іспанської
+    },
+  },
+};
+```
+
+Це дозволяє мати різну поведінку заповнення для різних локалей у межах одного проєкту.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  fill: "./example.content.json",
+  content: {
+    contentExample: "Це приклад вмісту",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Ось [файл декларації вмісту на рівні локалі](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/per_locale_file.md), який використовує інструкцію `fill`.
+
+Потім, коли ви виконаєте наступну команду:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer автоматично згенерує похідний файл декларації за адресою `src/components/example/example.content.json`, заповнивши всі локалі, які ще не оголошені в основному файлі.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "uk": "Це приклад вмісту",
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+Після цього обидва файли декларацій будуть об'єднані в один словник, доступний за допомогою стандартного хука `useIntlayer("example")` (React) / composable (Vue).
+
+## Глобальна конфігурація
+
+Ви можете налаштувати глобальну конфігурацію автоматичного заповнення у файлі `intlayer.config.ts`.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // Автоматично згенерувати відсутні переклади для всіх словників
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // автоматично згенерувати відсутні переклади для всіх словників, як при використанні "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+Ви все ще можете тонко налаштувати для кожного словника, використовуючи поле `fill` у файлах контенту. Intlayer спочатку врахує конфігурацію для конкретного словника, а потім відкотиться до глобальної конфігурації.
+
+## Формат автозаповнених файлів
+
+Рекомендований формат для автозаповнених файлів декларацій — **JSON**, оскільки це допомагає уникнути обмежень форматування. Однак Intlayer також підтримує `.ts`, `.js`, `.mjs`, `.cjs` та інші формати.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "./example.filled.content.ts",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує файл за шляхом:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> Генерація `.js`, `.ts` та схожих файлів працює таким чином:
+>
+> - Якщо файл вже існує, Intlayer розпарсить його, використовуючи AST (Abstract Syntax Tree), щоб знайти кожне поле та вставити будь-які відсутні переклади.
+> - Якщо файл не існує, Intlayer згенерує його, використовуючи шаблон файлу декларації контенту за замовчуванням.
+
+## Абсолютні шляхи
+
+Поле `fill` також підтримує абсолютні шляхи.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "/messages/example.content.json",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує файл за шляхом:
+
+```
+/messages/example.content.json
+```
+
+## Автогенерація файлів декларацій контенту для кожної локалі
+
+Поле `fill` також підтримує генерацію **файлів декларацій контенту для кожної локалі**.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує два окремі файли:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+> У цьому випадку, якщо об'єкт не містить усіх локалей, Intlayer пропустить генерацію решти локалей.
+
+## Фільтрація автозаповнення для певної локалі
+
+Використання об'єкта у полі `fill` дозволяє застосовувати фільтри та генерувати лише файли для певних локалей.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує лише файл перекладу французькою.
+
+## Змінні шляху
+
+Ви можете використовувати змінні всередині шляху `fill`, щоб динамічно формувати цільові шляхи для згенерованих файлів.
+
+**Доступні змінні:**
+
+- `{{locale}}` – код локалі (наприклад `fr`, `es`)
+- `{{fileName}}` – ім'я файлу (наприклад `index`)
+- `{{key}}` – ключ словника (наприклад `example`)
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Ваш вміст
+  },
+};
+```
+
+Це згенерує:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "./{{fileName}}.content.json",
+  content: {
+    // Ваш вміст
+  },
+};
+```
+
+Це згенерує:
+
+/// `./index.content.json`
+/// `./index.content.json`

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`