@intlayer/docs 7.0.0-canary.2 → 7.0.0-canary.3

package/docs/ru/releases/v7.md

@@ -0,0 +1,486 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Новый Intlayer v7 - Что нового?
+description: Узнайте, что нового в Intlayer v7. Значительные улучшения производительности, опыта разработчика и новые функции для улучшения вашего процесса интернационализации.
+keywords:
+  - Intlayer
+  - Локализация
+  - Разработка
+  - Производительность
+  - Опыт разработчика
+  - Функции
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# Новый Intlayer v7 - Что нового?
+
+Добро пожаловать в Intlayer v7! Этот крупный релиз представляет значительные улучшения в производительности, безопасности типов и опыте разработчика. Ниже приведены основные моменты, а также заметки по миграции и практические примеры.
+
+## Основные моменты
+
+- Стратегия кэширования для ускорения сборок
+- Улучшенная генерация типов TypeScript с типами, специфичными для локали
+- Оптимизация бандла: локали как строки вместо enum
+- Новые режимы маршрутизации: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- Хранение локали в соответствии с GDPR с использованием localStorage по умолчанию
+- Гибкая конфигурация хранения: cookies, localStorage, sessionStorage или несколько одновременно
+- Размер пакета Visual Editor уменьшен на 30%
+- Расширенные опции конфигурации middleware
+- Обновленное поведение команды fill для лучшего управления контентом
+- Повышенная стабильность с полным обновлением файлов деклараций контента
+- Интеллектуальное управление повторными попытками для точности перевода
+- Параллелизация для ускорения обработки переводов
+- Умное разбиение на чанки для работы с большими файлами в пределах ограничений AI контекста
+
+---
+
+## Производительность: Кэширование для ускорения сборок
+
+Вместо повторной сборки деклараций контента с помощью esbuild при каждой сборке, в версии 7 реализована стратегия кэширования, которая ускоряет процесс сборки.
+
+```bash
+npx intlayer build
+```
+
+Новая система кэширования:
+
+- Сохраняет скомпилированные декларации контента, чтобы избежать повторной обработки
+- Обнаруживает изменения и перестраивает только изменённые файлы
+- Значительно сокращает время сборки для крупных проектов
+
+---
+
+## TypeScript: Генерация типов, специфичных для локали
+
+Типы TypeScript теперь генерируются для каждой локали отдельно, обеспечивая более строгую типизацию и устраняя объединённые типы для всех локалей.
+
+**Поведение в 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` больше не является перечислением (enum), что означает, что он теперь полностью поддаётся tree-shaking и не будет раздувать ваш бандл тысячами неиспользуемых записей локалей.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Перечисление, включающее все локали -> не поддаётся tree-shaking
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Тип строки -> полностью поддаётся tree-shaking
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Поскольку `Locales` больше не является перечислением (enum), вам нужно будет изменить тип с `Locales` на `Locale`, чтобы получить локаль в виде типа.
+
+Подробнее смотрите в [реализации](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts).
+
+---
+
+## Новые режимы маршрутизации для большей гибкости
+
+В версии 7 введена единая конфигурация `routing.mode`, которая заменяет предыдущие опции `prefixDefault` и `noPrefix`, предоставляя более детальный контроль над структурой URL.
+
+### Доступные режимы маршрутизации
+
+- **`prefix-no-default`** (по умолчанию): у локали по умолчанию нет префикса, у остальных локалей префикс есть
+  - `/dashboard` (en) или `/fr/dashboard` (fr)
+- **`prefix-all`**: у всех локалей есть префикс
+  - `/en/dashboard` (en) или `/fr/dashboard` (fr)
+- **`no-prefix`**: Нет префиксов локали в URL (локаль обрабатывается через хранилище/заголовки)
+  - `/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, избегая необходимости получать согласие на использование cookies для предпочтений локали.
+
+### Опции конфигурации хранения
+
+Новое поле `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
+
+Для производственных приложений, которым нужно сбалансировать функциональность и соответствие GDPR:
+
+```typescript
+// 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");
+```
+
+**Примечание:** По умолчанию куки включены.
+**Примечание:** Ознакомьтесь с [требованиями GDPR к куки](https://gdpr.eu/cookies/) для вашего конкретного случая.
+
+---
+
+## Визуальный редактор: пакет стал на 30% меньше
+
+Пакет Визуального редактора был оптимизирован и стал на 30% меньше по сравнению с предыдущей версией благодаря:
+
+- Улучшению производительности редактора кода
+- Удалению ненужных зависимостей от основных пакетов Intlayer
+- Лучшей tree-shaking и упаковке модулей
+
+Это приводит к более быстрой загрузке и улучшенной производительности приложения во время выполнения.
+
+---
+
+## Команда fill: обновленное поведение для лучшего управления контентом
+
+v7 вводит улучшенное поведение команды `fill`, обеспечивая более предсказуемое и гибкое управление контентом:
+
+### Новое поведение fill
+
+- **`fill: true`** — Перезаписывает текущий файл заполненным контентом для всех локалей
+- **`fill: "path/to/file"`** — Заполняет указанный файл без изменения текущего файла
+- **`fill: false`** — Полностью отключает авто-заполнение
+
+### Расширенная поддержка сложных структур контента
+
+Команда fill теперь поддерживает сложные структуры деклараций контента, включая:
+
+- **Составные объекты**: декларации контента, которые ссылаются на другие объекты
+- **Деструктурированный контент**: контент, использующий паттерны деструктуризации
+- **Вложенные ссылки**: объекты, которые вызывают друг друга в сложных иерархиях
+- **Динамические структуры контента**: контент с условными или вычисляемыми свойствами
+
+### Преимущества
+
+- **Более ясное намерение**: поведение теперь более явно указывает, что именно изменяется
+- **Лучшее разделение**: Файлы с контентом могут храниться отдельно от заполненных переводов
+- **Улучшенный рабочий процесс**: Разработчики получают больше контроля над тем, где хранятся переводы
+- **Поддержка сложных структур**: Обработка сложных архитектур контента с множеством взаимосвязанных объектов
+
+### Пример использования
+
+```typescript
+// Перезаписать текущий файл со всеми локалями
+const content = {
+  key: "example",
+  fill: true, // Перезаписывает этот файл
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Заполнить отдельный файл без изменения текущего файла
+const content = {
+  key: "example",
+  fill: "./translations.json", // Создаёт/обновляет translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Отключить авто-заполнение
+const content = {
+  key: "example",
+  fill: false, // Авто-заполнение отключено
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Сложная структура контента с составными объектами
+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}`, а не частично, обеспечивая:
+
+- **Целостность данных**: Полная перезапись файла предотвращает частичные обновления, которые могут повредить содержимое
+- **Согласованность**: Все локали обновляются атомарно, поддерживая синхронизацию
+- **Надежность**: Снижает риск неполных или поврежденных файлов содержимого
+
+### Интеллектуальное управление повторными попытками
+
+Новые механизмы повторных попыток предотвращают отправку содержимого в неправильных форматах и избегают срыва всего процесса заполнения, если один из запросов не удался.
+
+### Параллелизация для ускорения обработки
+
+Операции перевода теперь выполняются в очереди с параллельным запуском, что значительно ускоряет процесс.
+
+### Умное разбиение на части для больших файлов
+
+Продвинутые стратегии разбиения обрабатывают большие файлы содержимого, не превышая контекстные окна ИИ:
+
+### Пример рабочего процесса
+
+```typescript
+// Большой файл содержимого автоматически разбивается на части
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Большое содержимое автоматически разбивается на части для обработки ИИ
+    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`
+
+### Сопоставление миграции
+
+#### Сопоставление конфигураций
+
+| Конфигурация v6            | Конфигурация v7                                         |
+| -------------------------- | ------------------------------------------------------- |
+| `autoFill: xxx`            | `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
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**После (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // или 'cookie', если требуется хранение в cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Соответствие содержимого словаря
+
+| Содержимое словаря v6 | Содержимое словаря v7 |
+| --------------------- | --------------------- |
+| `autoFill: xxx`       | `fill: xxx`           |
+
+#### Пример миграции
+
+**До (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Перезаписывает этот файл
+  content: {
+    title: "Привет, мир",
+  },
+};
+```
+
+**После (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // Перезаписывает этот файл
+  content: {
+    title: "Привет, мир",
+  },
+};
+```
+
+---
+
+## Заметки по миграции с v5 на v6
+
+Подробнее смотрите в [заметках по миграции с v5 на v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/releases/v6.md).
+
+---
+
+## Полезные ссылки
+
+- [Справочник по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
+- [Документация по Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/packages/next-intlayer/index.md)
+- [Типы TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Руководство по cookie в соответствии с GDPR](https://gdpr.eu/cookies/)