Новый 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 реализована стратегия кэширования, которая ускоряет процесс сборки.

npx intlayer build

Новая система кэширования:

• Сохраняет скомпилированные декларации контента, чтобы избежать повторной обработки
• Обнаруживает изменения и перестраивает только изменённые файлы
• Значительно сокращает время сборки для крупных проектов

TypeScript: Генерация типов, специфичных для локали

Типы TypeScript теперь генерируются для каждой локали отдельно, обеспечивая более строгую типизацию и устраняя объединённые типы для всех локалей.

Поведение в v6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Поведение в v7:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Преимущества:

• Более точное автозаполнение в вашей IDE
• Лучшая типобезопасность без смешения типов между локалями
• Повышенная производительность за счёт уменьшения сложности типов

Оптимизация бандла: Локали как строки

Тип Locales больше не является перечислением (enum), что означает, что он теперь полностью поддаётся tree-shaking и не будет раздувать ваш бандл тысячами неиспользуемых записей локалей.

v6:

import { Locales } from "intlayer";// Перечисление, включающее все локали -> не поддаётся tree-shakingconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Тип строки -> полностью поддаётся tree-shakingconst locale: Locale = Locales.ENGLISH;

Поскольку Locales больше не является перечислением (enum), вам нужно будет изменить тип с Locales на Locale, чтобы получить локаль в виде типа.

Подробнее смотрите в реализации.

Новые режимы маршрутизации для большей гибкости

В версии 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

Базовая конфигурация

// intlayer.config.tsexport 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, предлагая гибкие конфигурации хранения:

// Отключить хранение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:

// intlayer.config.tsexport 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:

Можно определить глобально:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Можно переопределить локально для каждого хука:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Примечание: По умолчанию куки включены. Примечание: Ознакомьтесь с требованиями GDPR к куки для вашего конкретного случая.

Визуальный редактор: пакет стал на 30% меньше

Пакет Визуального редактора был оптимизирован и стал на 30% меньше по сравнению с предыдущей версией благодаря:

• Улучшению производительности редактора кода
• Удалению ненужных зависимостей от основных пакетов Intlayer
• Лучшей tree-shaking и упаковке модулей

Это приводит к более быстрой загрузке и улучшенной производительности приложения во время выполнения.

Команда fill: обновленное поведение для лучшего управления контентом

v7 вводит улучшенное поведение команды fill, обеспечивая более предсказуемое и гибкое управление контентом:

Новое поведение fill

• fill: true — Перезаписывает текущий файл заполненным контентом для всех локалей
• fill: "path/to/file" — Заполняет указанный файл без изменения текущего файла
• fill: false — Полностью отключает авто-заполнение

Расширенная поддержка сложных структур контента

Команда fill теперь поддерживает сложные структуры деклараций контента, включая:

• Составные объекты: декларации контента, которые ссылаются на другие объекты
• Деструктурированный контент: контент, использующий паттерны деструктуризации
• Вложенные ссылки: объекты, которые вызывают друг друга в сложных иерархиях
• Динамические структуры контента: контент с условными или вычисляемыми свойствами

Преимущества

• Более ясное намерение: поведение теперь более явно указывает, что именно изменяется
• Лучшее разделение: Файлы с контентом могут храниться отдельно от заполненных переводов
• Улучшенный рабочий процесс: Разработчики получают больше контроля над тем, где хранятся переводы
• Поддержка сложных структур: Обработка сложных архитектур контента с множеством взаимосвязанных объектов

Пример использования

// Перезаписать текущий файл со всеми локалями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}, а не частично, обеспечивая:

• Целостность данных: Полная перезапись файла предотвращает частичные обновления, которые могут повредить содержимое
• Согласованность: Все локали обновляются атомарно, поддерживая синхронизацию
• Надежность: Снижает риск неполных или поврежденных файлов содержимого

Интеллектуальное управление повторными попытками

Новые механизмы повторных попыток предотвращают отправку содержимого в неправильных форматах и избегают срыва всего процесса заполнения, если один из запросов не удался.

Параллелизация для ускорения обработки

Операции перевода теперь выполняются в очереди с параллельным запуском, что значительно ускоряет процесс.

Умное разбиение на части для больших файлов

Продвинутые стратегии разбиения обрабатывают большие файлы содержимого, не превышая контекстные окна ИИ:

Пример рабочего процесса

// Большой файл содержимого автоматически разбивается на части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):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

После (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // или 'cookie', если требуется хранение в cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Соответствие содержимого словаря

Пример миграции

До (v6):

const content = {  key: "example",  autoFill: true, // Перезаписывает этот файл  content: {    title: "Привет, мир",  },};

После (v7):

const content = {  key: "example",  fill: true, // Перезаписывает этот файл  content: {    title: "Привет, мир",  },};

Заметки по миграции с v5 на v6

Подробнее смотрите в заметках по миграции с v5 на v6.

Полезные ссылки

• Справочник по конфигурации
• Документация по Middleware
• Типы TypeScript
• Руководство по cookie в соответствии с GDPR