Що нового в 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 реалізовано стратегію кешування, яка пришвидшує процес збірки.

npx intlayer build

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

• Зберігає скомпільовані декларації контенту, щоб уникнути повторної обробки
• Виявляє зміни та перебудовує лише змінені файли
• Значно скорочує час збірки для великих проєктів

TypeScript: Генерація типів для кожної локалі

Типи TypeScript тепер генеруються для кожної локалі, що забезпечує надійнішу типізацію та усуває union-типи між усіма локалями.

Поведінка 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 як рядки

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

v6:

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

v7:

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

Оскільки Locales більше не є enum, вам доведеться змінити тип з Locales на Locale, щоб отримувати локаль як тип.

Див. деталі реалізації для додаткової інформації.

Нові режими маршрутизації для більшої гнучкості

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

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

// intlayer.config.tsexport 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, що дає змогу гнучко налаштовувати сховище:

// Вимкнути зберігання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:

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");

Примітка: За замовчуванням файли cookie ввімкнені. Примітка: Перевірте вимоги до cookie відповідно до 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',  },};

Підтримувані форматувачі

Ви можете використовувати будь-який форматувач коду, який приймає шляхи до файлів як аргументи:

За допомогою Biome:

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

За допомогою Prettier:

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

За допомогою ESLint:

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

За допомогою вбудованого форматувача Bun:

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:

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

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

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: Опис за замовчуванням для нового контенту

Для отримання додаткової інформації про файли декларації контенту та про те, як застосовуються конфігураційні значення, див. Документацію файлу контенту.

Команда fill: оновлена поведінка для кращого управління контентом

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

Нова поведінка fill

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

Розширена підтримка складних структур контенту

Команда fill тепер підтримує складні структури декларацій контенту, включно з:

• Складені об'єкти: Оголошення контенту, які посилаються на інші об'єкти
• Деструктуризований контент: Контент, що використовує патерни деструктуризації
• Вкладені посилання: Об'єкти, які посилаються один на одного у складних ієрархіях
• Динамічні структури контенту: Контент з умовними або обчислюваними властивостями

Переваги

• Чіткіший намір: Поведінка тепер більш явна щодо того, що змінюється
• Краще розділення: Файли контенту можна зберігати окремо від заповнених перекладів
• Покращений робочий процес: Розробники отримують більший контроль над тим, де зберігаються переклади
• Підтримка складних структур: Обробка складних архітектур контенту з кількома взаємопов'язаними об'єктами

Приклад використання

// Перезаписати поточний файл для всіх локалей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:

Приклад робочого процесу

// Великий файл контенту автоматично розбивається на частини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):

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):

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):

const content = {  key: "example",  autoFill: true, // Перезаписує цей файл  content: {    title: "Hello World",  },};

Після (v7):

const content = {  key: "example",  fill: true, // Перезаписує цей файл  content: {    title: "Hello World",  },};

Нотатки міграції з v5 до v6

Перегляньте нотатки міграції з v5 до v6 для отримання додаткової інформації.

Корисні посилання

• Довідник конфігурації
• Документація middleware
• Типи TypeScript
• Рекомендації GDPR щодо cookie