Новый 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

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

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

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-shaking

const locale: Locales = Locales.ENGLISH;

v7:

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

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

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

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

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

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

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

setLocale("en");

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

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

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

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

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

Автоматическое форматирование кода: конфигурация formatCommand

v7 вводит опцию formatCommand в конфигурации редактора, позволяя вам автоматически форматировать файлы содержимого при их записи Intlayer. Это обеспечивает согласованный стиль кода и форматирование во всех файлах объявления контента.

Если не установлено, Intlayer попытается автоматически определить команду форматирования. Путем попытки разрешить следующие команды: prettier, biome, eslint.

Конфигурация

Опция formatCommand принимает строковый шаблон, где {{file}} будет заменена на фактический путь файла:

export default {
  content: {
    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
  },
};

Поддерживаемые форматеры

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

Using Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Using Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Using ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Using Bun's built-in formatter:

formatCommand: 'bun format "{{file}}"';

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

• Согласованное форматирование: Все файлы содержимого автоматически форматируются в соответствии с рекомендациями стиля вашего проекта
• Опыт разработчика: Нет необходимости вручную форматировать файлы после их создания Intlayer
• Согласованность команды: Гарантирует, что все члены команды имеют одинаковое форматирование, применяемое к файлам содержимого
• Интеграция CI/CD: Файлы содержимого сохраняют согласованное форматирование в автоматизированных рабочих процессах

Как это работает

When Intlayer writes or updates a content declaration file (.content.ts, .content.js, etc.), it automatically runs the specified format command on the file. The {{file}} placeholder is replaced with the actual file path, and the command is executed in the project's base directory.

Dictionary Configuration: Better organization and structure

v7 представляет новый dedicated раздел конфигурации dictionary, который обеспечивает лучшую организацию параметров, связанных со словарем, и улучшенное управление содержимым.

Новая структура конфигурации словаря

Свойство fill было перемещено из раздела content в новый раздел dictionary, обеспечивая более четкое разделение ответственности:

Конфигурация v6:

export default {
  content: {
    autoFill: "./{{fileName}}.content.json",
    contentDir: ["src"],
  },
};

Конфигурация v7:

export default {
  content: {
    contentDir: ["src"],
  },
  dictionary: {
    fill: "./{{fileName}}.content.json",
  },
};

Преимущества новой структуры

• Более четкая организация: Параметры, характерные для словаря, теперь сгруппированы вместе
• Лучшее разделение ответственности: Обнаружение содержимого и операции со словарем четко разделены
• Улучшенная поддерживаемость: Легче понять и модифицировать конфигурации, связанные со словарем
• Будущая расширяемость: Раздел словаря может вмещать дополнительные параметры, характерные для словаря
• Комплексное управление словарем: Включает свойства, такие как title, live, priority, tags, version и description для создания и управления новыми словарями

Использование конфигурации

Конфигурация словаря служит двум основным целям:

1. Значения по умолчанию: Определение значений по умолчанию при создании файлов объявления контента
2. Поведение при отсутствии значения: Предоставление резервных значений, когда определенные поля не определены, позволяя вам глобально определить поведение операций словаря

Раздел словаря включает комплексные свойства для управления словарем:

• fill: Поведение автозаполнения при генерации контента
• title: Заголовок по умолчанию для новых словарей
• live: Конфигурация синхронизации в реальном времени для обновлений
• priority: Параметры приоритета для разрешения словаря
• tags: Теги по умолчанию для организации контента
• version: Управление версиями для обновлений словаря
• description: Описание по умолчанию для нового контента

Для получения дополнительной информации о файлах объявления контента и применении значений конфигурации см. Документация по файлам контента.

Команда 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

Новые конфигурации

• editor.formatCommand: Новый параметр для автоматического форматирования кода файлов содержимого

Сопоставление миграции

Сопоставление конфигураций

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

До (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