@intlayer/docs 7.5.12 → 7.5.13

package/docs/uk/releases/v7.md

@@ -0,0 +1,624 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Що нового в Intlayer v7?
+description: Дізнайтесь, що нового в Intlayer v7. Значні покращення продуктивності, developer experience та нові функції для покращення вашого internationalization workflow.
+keywords:
+  - Intlayer
+  - Локалізація
+  - Розробка
+  - Продуктивність
+  - Досвід розробника
+  - Функції
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# Що нового в Intlayer v7?
+
+Ласкаво просимо до Intlayer v7! Це велике оновлення вводить суттєві покращення продуктивності, type safety і developer experience. Нижче наведено основні зміни, нотатки щодо міграції та практичні приклади.
+
+## Основні моменти
+
+- Підтримка Next.js 16
+- Стратегія кешування для прискорення збірок
+- Покращене генерування типів TypeScript з типами, специфічними для локалі
+- Оптимізація бандла: локалі як рядки замість enum
+- Нові режими маршрутизації: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- GDPR-сумісність при використанні localStorage
+- Гнучка конфігурація збереження: cookies, localStorage, sessionStorage або кілька одночасно
+- Розмір пакету Visual Editor зменшено на 30%
+- Розширені параметри конфігурації middleware
+- Оновлена поведінка команди fill для кращого управління контентом
+- Нова секція конфігурації dictionary для кращої організації
+- Підвищена стабільність завдяки повним оновленням файлів декларацій контенту
+- Інтелектуальне керування повторними спробами для підвищення точності перекладу
+- Паралелізація для швидшої обробки перекладів
+- Розумне дроблення (smart chunking) для обробки великих файлів у межах лімітів контексту AI
+- Автоматичне форматування коду з настроюваною командою formatCommand
+
+---
+
+## Продуктивність: Кешування для швидших збірок
+
+Замість перебудови декларацій контенту за допомогою esbuild при кожній збірці, у v7 реалізовано стратегію кешування, яка пришвидшує процес збірки.
+
+```bash
+npx intlayer build
+```
+
+Нова система кешування:
+
+- Зберігає скомпільовані декларації контенту, щоб уникнути повторної обробки
+- Виявляє зміни та перебудовує лише змінені файли
+- Значно скорочує час збірки для великих проєктів
+
+---
+
+## TypeScript: Генерація типів для кожної локалі
+
+Типи TypeScript тепер генеруються для кожної локалі, що забезпечує надійнішу типізацію та усуває union-типи між усіма локалями.
+
+**Поведінка v6:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Поведінка v7:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+Переваги:
+
+- Більш точне автозаповнення в IDE
+- Краща безпека типів без перехресного забруднення типів між локалями
+- Покращена продуктивність за рахунок зменшення складності типів
+
+---
+
+## Оптимізація бандла: Locales як рядки
+
+Тип `Locales` більше не є enum, тому він тепер повністю піддається tree-shaking і не роздуватиме ваш бандл тисячами невикористаних записів локалі.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum, що включає всі локалі -> не піддається tree-shaking
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Тип рядка -> повністю tree-shakeable
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Оскільки `Locales` більше не є enum, вам доведеться змінити тип з `Locales` на `Locale`, щоб отримувати локаль як тип.
+
+Див. [деталі реалізації](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) для додаткової інформації.
+
+---
+
+## Нові режими маршрутизації для більшої гнучкості
+
+v7 вводить уніфіковану конфігурацію `routing.mode`, яка замінює попередні опції `prefixDefault` та `noPrefix`, надаючи більш детальний контроль над структурою URL.
+
+### Доступні режими маршрутизації
+
+- **`prefix-no-default`** (за замовчуванням): локаль за замовчуванням без префікса, інші локалі — з префіксом
+  - `/dashboard` (en) або `/fr/dashboard` (fr)
+- **`prefix-all`**: У всіх локалей є префікс
+  - `/en/dashboard` (en) або `/fr/dashboard` (fr)
+- **`no-prefix`**: Жодних префіксів локалі в URL (локаль обробляється через storage/headers)
+  - `/dashboard` для всіх локалей
+- **`search-params`**: Локаль передається як параметр запиту
+  - `/dashboard?locale=en` або `/dashboard?locale=fr`
+
+### Базова конфігурація
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // за замовчуванням
+  },
+};
+```
+
+---
+
+## Відповідність GDPR: localStorage / cookies
+
+v7 надає пріоритет конфіденційності користувача, використовуючи `localStorage` як механізм зберігання за замовчуванням замість cookies. Ця зміна допомагає відповідати вимогам GDPR, оскільки дозволяє уникнути необхідності отримання згоди на використання cookie для налаштувань локалі.
+
+### Опції конфігурації сховища
+
+Нове поле `routing.storage` доступне на додаток до попередніх опцій `middleware.cookieName` та `middleware.serverSetCookie`, що дає змогу гнучко налаштовувати сховище:
+
+```typescript
+// Вимкнути зберігання
+storage: false
+
+// Прості типи сховища
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie з власними атрибутами
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage з власним ключем
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Кілька типів сховища для резервування
+storage: ['cookie', 'localStorage']
+```
+
+### Приклад конфігурації, що відповідає GDPR
+
+Для production-застосунків, яким потрібно знайти баланс між функціональністю та відповідністю GDPR:
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // Первинне сховище (не потребує згоди)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // Опційне cookie-сховище (потребує згоди)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### Увімкнення / вимкнення збереження в cookie
+
+Приклад використання React / Next.js:
+
+Можна визначити глобально:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Можна перевизначити локально для кожного хука:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Примітка:** За замовчуванням файли cookie ввімкнені.
+**Примітка:** Перевірте [вимоги до cookie відповідно до GDPR](https://gdpr.eu/cookies/) для вашого конкретного випадку використання.
+
+---
+
+## Візуальний редактор: пакет на 30% менший
+
+Пакет Візуального редактора оптимізовано — він став на 30% меншим порівняно з попередньою версією завдяки:
+
+- Покращенням продуктивності редактора коду
+- Видаленню непотрібних залежностей від базових пакетів Intlayer
+- Кращому tree-shaking та бандлінгу модулів
+
+Це призводить до швидшого завантаження та покращеної продуктивності під час виконання вашого додатка.
+
+---
+
+## Автоматичне форматування коду: конфігурація formatCommand
+
+У v7 введено опцію `formatCommand` у конфігурації редактора, яка дозволяє автоматично форматувати файли вмісту під час їхнього запису Intlayer. Це забезпечує послідовний стиль коду та форматування у ваших файлах декларацій вмісту.
+
+Якщо не вказано, Intlayer спробує автоматично визначити команду форматування, пробуючи знайти одну з наступних команд: prettier, biome, eslint.
+
+### Конфігурація
+
+Опція `formatCommand` приймає рядковий шаблон, у якому `{{file}}` буде замінено на фактичний шлях до файлу:
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
+  },
+};
+```
+
+### Підтримувані форматувачі
+
+Ви можете використовувати будь-який форматувач коду, який приймає шляхи до файлів як аргументи:
+
+**За допомогою Biome:**
+
+```typescript
+formatCommand: 'bun x biome format "{{file}}" --write --log-level none';
+```
+
+**За допомогою Prettier:**
+
+```typescript
+formatCommand: 'npx prettier --write "{{file}}" --log-level silent';
+```
+
+**За допомогою ESLint:**
+
+```typescript
+formatCommand: 'npx eslint --fix "{{file}}" --quiet';
+```
+
+**За допомогою вбудованого форматувача Bun:**
+
+```typescript
+formatCommand: 'bun format "{{file}}"';
+```
+
+### Переваги
+
+- **Послідовне форматування**: Всі файли контенту автоматично форматуються відповідно до правил стилю вашого проєкту
+- **Developer experience**: немає потреби вручну форматувати файли після того, як Intlayer їх записує
+- **Team consistency**: забезпечує, що всі члени команди мають однакове форматування файлів контенту
+- **CI/CD integration**: файли контенту зберігають узгоджене форматування в автоматизованих воркфлоу
+
+### Як це працює
+
+Коли Intlayer записує або оновлює файл декларації контенту (`.content.ts`, `.content.js` тощо), він автоматично запускає вказану команду форматування для цього файлу. Плейсхолдер `{{file}}` замінюється на фактичний шлях до файлу, а команда виконується в кореневому каталозі проєкту.
+
+---
+
+## Конфігурація словника: краща організація та структура
+
+v7 додає новий спеціальний розділ конфігурації `dictionary`, який забезпечує кращу організацію налаштувань, пов'язаних зі словниками, та покращене керування контентом.
+
+### Нова структура конфігурації `dictionary`
+
+Властивість `fill` була переміщена з розділу `content` до нового розділу `dictionary`, що забезпечує чіткіше розмежування відповідальностей:
+
+**Конфігурація v6:**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    autoFill: "./{{fileName}}.content.json",
+    contentDir: ["src"],
+  },
+};
+```
+
+**Конфігурація v7:**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    contentDir: ["src"],
+  },
+  dictionary: {
+    fill: "./{{fileName}}.content.json",
+  },
+};
+```
+
+### Переваги нової структури
+
+- **Чіткіша організація**: налаштування, специфічні для `dictionary`, тепер згруповані разом
+- **Кращий розподіл відповідальностей**: виявлення `content` та операції `dictionary` чітко розділені
+- **Покращена підтримуваність**: легше розуміти та змінювати конфігурації, пов'язані з `dictionary`
+- **Майбутнє розширення**: секція `dictionary` може вміщувати додаткові налаштування, специфічні для словників
+- **Комплексне керування dictionary**: включає властивості, такі як `title`, `live`, `priority`, `tags`, `version` та `description` для створення та керування новими словниками
+
+### Використання конфігурації
+
+Конфігурація `dictionary` виконує дві основні функції:
+
+1. **Значення за замовчуванням**: визначає значення за замовчуванням при створенні файлів декларації `content`
+2. **Поведінка запасних значень (Fallback Behavior)**: Надає запасні значення (fallback), коли конкретні поля не визначені, що дозволяє задавати поведінку операцій словника глобально
+
+Розділ словника включає вичерпні властивості для керування словниками:
+
+- **`fill`**: Поведінка автозаповнення при генерації контенту
+- **`title`**: Заголовок за замовчуванням для нових словників
+- **`live`**: Налаштування live-синхронізації для оновлень у реальному часі
+- **`priority`**: Налаштування пріоритетів для визначення словника
+- **`tags`**: Теги за замовчуванням для організації контенту
+- **`version`**: Керування версіями для оновлень словника
+- **`description`**: Опис за замовчуванням для нового контенту
+
+Для отримання додаткової інформації про файли декларації контенту та про те, як застосовуються конфігураційні значення, див. [Документацію файлу контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md).
+
+---
+
+## Команда fill: оновлена поведінка для кращого управління контентом
+
+v7 вводить покращену поведінку для команди `fill`, забезпечуючи більш передбачуване та гнучке управління контентом:
+
+### Нова поведінка fill
+
+- **`fill: true`** - Перезаписує поточний файл заповненим контентом для всіх локалей
+- **`fill: "path/to/file"`** - Заповнює вказаний файл без зміни поточного файлу
+- **`fill: false`** - Повністю відключає автоматичне заповнення
+
+### Розширена підтримка складних структур контенту
+
+Команда fill тепер підтримує складні структури декларацій контенту, включно з:
+
+- **Складені об'єкти**: Оголошення контенту, які посилаються на інші об'єкти
+- **Деструктуризований контент**: Контент, що використовує патерни деструктуризації
+- **Вкладені посилання**: Об'єкти, які посилаються один на одного у складних ієрархіях
+- **Динамічні структури контенту**: Контент з умовними або обчислюваними властивостями
+
+### Переваги
+
+- **Чіткіший намір**: Поведінка тепер більш явна щодо того, що змінюється
+- **Краще розділення**: Файли контенту можна зберігати окремо від заповнених перекладів
+- **Покращений робочий процес**: Розробники отримують більший контроль над тим, де зберігаються переклади
+- **Підтримка складних структур**: Обробка складних архітектур контенту з кількома взаємопов'язаними об'єктами
+
+### Приклад використання
+
+```typescript fileName="*.content.ts"
+// Перезаписати поточний файл для всіх локалей
+const content = {
+  key: "example",
+  fill: true, // Перезаписує цей файл
+  content: {
+    title: "Привіт, світ",
+  },
+};
+
+// Заповнити окремий файл без модифікації поточного файлу
+const content = {
+  key: "example",
+  fill: "./translations.json", // Створює/оновлює translations.json
+  content: {
+    title: "Привіт, світ",
+  },
+};
+
+// Вимкнути автозаповнення
+const content = {
+  key: "example",
+  fill: false, // Автозаповнення вимкнено
+  content: {
+    title: "Привіт, світ",
+  },
+};
+
+// Складна структура контенту з композиційними об'єктами
+const sharedContent = {
+  buttons: {
+    save: "Зберегти",
+    cancel: "Скасувати",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // Посилання на інші об'єкти
+    sharedContent,
+
+    // Деструктурований контент
+    ...sharedContent,
+
+    // Вкладені посилання
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "Розділ 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## Покращена стабільність і керування перекладами
+
+v7 представляє кілька покращень, що роблять переклад контенту більш надійним і ефективним:
+
+### Повне оновлення файлів декларації вмісту
+
+Система тепер оновлює файли `.content.{ts,js,cjs,mjs}` цілком, замість часткових оновлень, забезпечуючи:
+
+- **Цілісність даних**: повні перезаписи файлів запобігають частковим оновленням, які можуть пошкодити вміст
+- **Послідовність**: усі локалі оновлюються атомарно, зберігаючи синхронізацію
+- **Надійність**: зменшує ризик неповних або пошкоджених файлів вмісту
+
+### Інтелектуальне керування повторними спробами
+
+Нові механізми повторних спроб запобігають відправленню контенту у невірних форматах і не дають зламатися всьому процесу заповнення, якщо один запит зазнає невдачі.
+
+### Паралелізація для швидшої обробки
+
+Операції перекладу тепер ставляться в чергу і виконуються паралельно. Це значно пришвидшує процес.
+
+### Інтелектуальне розбиття на частини для великих файлів
+
+Розвинені стратегії розбиття справляються з великими файлами контенту, не перевищуючи контекстні вікна AI:
+
+### Приклад робочого процесу
+
+```typescript fileName="*.content.ts"
+// Великий файл контенту автоматично розбивається на частини
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Великий контент автоматично розбивається для обробки AI
+    introduction: "..." // 5000+ символів
+    sections: [
+      // Кілька великих секцій
+    ]
+  }
+};
+```
+
+Система автоматично:
+
+1. Аналізує розмір і структуру контенту
+2. Розбиває контент на частини відповідним чином
+3. Обробляє частини паралельно
+4. Перевіряє й повторює у разі потреби
+5. Відновлює повний файл
+
+---
+
+## Нотатки щодо міграції з v6
+
+### Вилучені конфігурації
+
+- **`middleware.cookieName`**: Замінено на `routing.storage`
+- **`middleware.serverSetCookie`**: Замінено на `routing.storage`
+- **`middleware.prefixDefault`**: Замінено на `routing.mode`
+- **`middleware.noPrefix`**: Замінено на `routing.mode`
+
+### Нові конфігурації
+
+- **`editor.formatCommand`**: Нова опція для автоматичного форматування коду файлів контенту
+
+### Відповідність налаштувань при міграції
+
+#### Відповідність конфігурацій
+
+| Конфігурація v6            | Конфігурація v7                                        |
+| -------------------------- | ------------------------------------------------------ |
+| `content.autoFill: xxx`    | `dictionary.fill: xxx`                                 |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                            |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                   |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                    |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`       |
+| `serverSetCookie: 'never'` | `storage: false` або видалити cookie зі масиву storage |
+
+#### Приклад міграції
+
+**До (v6):**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    autoFill: "./{{fileName}}.content.json",
+    contentDir: ["src"],
+  },
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**Після (v7):**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    contentDir: ["src"],
+  },
+  dictionary: {
+    fill: "./{{fileName}}.content.json",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // або 'cookie', якщо вам потрібне збереження в cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+  },
+  editor: {
+    formatCommand: 'bun x biome format "{{file}}" --write --log-level none', // Необов'язково: автоматичне форматування
+  },
+};
+```
+
+#### Відповідність вмісту словника
+
+| Вміст словника (v6) | Вміст словника (v7) |
+| ------------------- | ------------------- |
+| `autoFill: xxx`     | `fill: xxx`         |
+
+#### Приклад міграції
+
+**До (v6):**
+
+```typescript fileName="*.content.ts"
+const content = {
+  key: "example",
+  autoFill: true, // Перезаписує цей файл
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**Після (v7):**
+
+```typescript fileName="*.content.ts"
+const content = {
+  key: "example",
+  fill: true, // Перезаписує цей файл
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+---
+
+## Нотатки міграції з v5 до v6
+
+Перегляньте [нотатки міграції з v5 до v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/releases/v6.md) для отримання додаткової інформації.
+
+---
+
+## Корисні посилання
+
+- [Довідник конфігурації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)
+- [Документація middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/next-intlayer/index.md)
+- [Типи TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Рекомендації GDPR щодо cookie](https://gdpr.eu/cookies/)