Ласкаво просимо до Intlayer v9! Цей мажорний реліз є величезною віхою у спрощенні шляху міграції на Intlayer завдяки Compat Adapter Packages (пакетам адаптерів сумісності) для основних бібліотек i18n (react-i18next, next-intl, vue-i18n тощо) та додає підтримку складних структур контенту: Collections (Колекцій), Variants (Варіантів) та Dynamic Records (Динамічних записів).

Зміст

Пакети адаптерів сумісності (Compat Adapter Packages)

Мігрувати на Intlayer з популярних бібліотек i18n тепер простіше, ніж будь-коли. Ми створили п'ять пакетів сумісності, які надають точно такий самий публічний API, як і стандартні бібліотеки i18n, але делегують усю роботу з перекладу Intlayer під час виконання (runtime).

Той самий публічний API зі строгою типізацією

Замінивши імпорти, ви отримуєте всі переваги Intlayer (включаючи типізацію на етапі компіляції відповідно до ваших реальних словників) з мінімальними змінами в коді:

@intlayer/i18next
@intlayer/react-i18next
@intlayer/next-intl
@intlayer/next-i18next
@intlayer/vue-i18n

Наприклад, просто змініть:

Копіювати код

Скопіюйте код у буфер обміну

import { useTranslation } from "react-i18next";

import { useTranslation } from "react-i18next";

на:

Копіювати код

Скопіюйте код у буфер обміну

import { useTranslation } from "@intlayer/react-i18next";

import { useTranslation } from "@intlayer/react-i18next";

Тепер ваші ключі будуть строго типізовані відповідно до ваших словників Intlayer, забезпечуючи повне автодоповнення шляхів через крапку (dot-path) у вашій IDE!

Плагіни аліасів для бандлерів (Vite, Next.js, Turbopack)

Щоб дозволити міграцію без ручного переписування всіх інструкцій імпорту, кожен пакет адаптера сумісності містить кастомний плагін для бандлера (Vite або Next.js) у підшляху /plugin.

Ці плагіни автоматично перезаписують існуючі імпорти (наприклад, react-i18next або next-intl) на їхні еквіваленти @intlayer/* під час збірки.

Приклад для Next.js (Webpack / Turbopack)

Замість withIntlayer оберніть вашу конфігурацію Next.js плагіном сумісності:

next.config.ts

Копіювати код

Скопіюйте код у буфер обміну

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

Приклад для Vite (React, Vue, Solid, Svelte)

vite.config.ts

Копіювати код

Скопіюйте код у буфер обміну

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

Спільний резолвер часу виконання (Mutualized Runtime Resolver)

Усі адаптери сумісності тепер направляють резолв перекладів через єдиний, високооптимізований парсер часу виконання: @intlayer/core/messageFormat.

Interpolate Message: Резолвить стандартні {{var}} (пробіли та dot-paths), аргументи у форматі ICU ({v, number, percent} тощо) та прості шаблони {var}.
Message Node Resolver: Резолвить вкладені вузли: insert(), plural() (правила множини CLDR), enu() (перелічення), gender(), HTML-теги, масиви та вузли функцій зворотного виклику (callable function nodes).
Tokenized Tag Parser: Підтримує інлайнові XML/HTML-теги та нумеровані теги (наприклад, <1>children</1>) для забезпечення рендерингу форматованого тексту (rich-text) "з коробки".

Специфікація функцій: Collections, Variants та Dynamic Records

Intlayer v9 виходить за рамки статичних об'єктів типу ключ-значення, дозволяючи словникам оголошувати динамічні структури макетів, які повністю типізовані від початку до кінця (end-to-end).

1. Колекції (Collections)

Визначайте керований CMS список упорядкованих елементів (наприклад, FAQ, товари або списки блогів):

faq.content.ts

Копіювати код

Скопіюйте код у буфер обміну

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  content: [    {      question: t({        uk: "Що таке Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        uk: "Інструментарій i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  content: [    {      question: t({        uk: "Що таке Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        uk: "Інструментарій i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

Використання:

Копіювати код

Скопіюйте код у буфер обміну

// Отримати всі елементиconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Отримати один елемент за індексомconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

// Отримати всі елементиconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Отримати один елемент за індексомconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. Варіанти (Variants)

Надавайте A/B тести, сезонні заголовки, feature flags або кастомні цільові сторінки (landing pages):

hero.content.ts

Копіювати код

Скопіюйте код у буфер обміну

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ uk: "Ласкаво просимо", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      uk: "Купити зараз",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ uk: "Ласкаво просимо", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      uk: "Купити зараз",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

Використання:

Копіювати код

Скопіюйте код у буфер обміну

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

3. Динамічні записи (Dynamic Records)

Визначайте словники, записи яких завантажуються динамічно під час виконання за допомогою ідентифікаторів запитів (query IDs):

product.content.ts

Копіювати код

Скопіюйте код у буфер обміну

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    id: "prod_123",    category: "books",  },  content: {    title: t({ uk: "Чистий код", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    id: "prod_123",    category: "books",  },  content: {    title: t({ uk: "Чистий код", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

Використання:

Копіювати код

Скопіюйте код у буфер обміну

// Динамічно завантажує лише запитуваний елемент (потребує Suspense)const product = useIntlayer("product-copy", {  id: "prod_123",  category: "books",});

// Динамічно завантажує лише запитуваний елемент (потребує Suspense)const product = useIntlayer("product-copy", {  id: "prod_123",  category: "books",});

Динамічне завантаження та оптимізація розміру бандла

Щоб зберегти розмір бандлів надзвичайно малим, Intlayer v9 підтримує динамічне ліниве завантаження (lazy loading).

У вашій конфігурації встановіть importMode у 'dynamic' або 'fetch':

intlayer.config.ts

Копіювати код

Скопіюйте код у буфер обміну

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

Під час збірки @intlayer/swc та @intlayer/babel сканують ваші файли та замінюють виклики useIntlayer / getIntlayer на tree-shakeable обгортки (useDictionary / useDictionaryDynamic). Завантажується лише контент, необхідний для вибраного елемента колекції, варіанта або локалі, що запобігає потраплянню невикористовуваних перекладів у ваш продакшн-бандл.

Примітки щодо міграції з v8

Якщо ви оновлюєтеся з v8, зверніть увагу, що v9 не містить критичних змін (breaking changes). Проте ось ключові зміни:

Locales & Dialects: Якщо ви використовуєте зовнішні залежності i18n, додайте відповідні плагіни адаптерів сумісності у вашу конфігурацію або налаштування бандлера для автоматичного перезапису імпортів.
Custom Selectors: При виклику useIntlayer другий параметр тепер зарезервований для об'єкта опцій, що містить { locale, item, variant, id }. Якщо раніше ви передавали рядок локалі безпосередньо, ви все ще можете це робити, але для розширеного вибору рекомендується використовувати об'єкт опцій.

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

Language Server Protocol