Новий Intlayer v9 - Що нового?

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

Зміст

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

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

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

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

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

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

import { useTranslation } from "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 плагіном сумісності:

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)

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

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

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

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

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

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

// Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

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

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

Рядкові варіанти (наприклад, A/B-тестування)

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

Об'єктні варіанти (наприклад, динамічні записи)

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

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

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

Vite Plugin: Bundled Compiler & Proxy

Плагін Vite intlayer() тепер об'єднує компілятор та проксі для маршрутизації локалей безпосередньо, тому більшості проектів потрібен лише один плагін у vite.config.ts:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

• Compiler: Активується автоматично, коли compiler.enabled встановлено у true та налаштовано шлях compiler.output. Вам більше не потрібно реєструвати intlayerCompiler() окремо.
• Proxy: Активується автоматично на основі нового параметра routing.enableProxy (true за замовчуванням). Він підключає middleware виявлення локалей / перенаправлення / переписування в режимі розробки, попереднього перегляду та production SSR. Вам більше не потрібно реєструвати intlayerProxy() окремо.

Опція routing.enableProxy

Нова опція routing.enableProxy контролює, чи підключений проксі маршрутизації локалі. За замовчуванням встановлено значення true. Вимкніть її, якщо ви хочете самостійно обробляти маршрутизацію локалі:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // За замовчуванням: true  },};export default config;

Автономні плагіни intlayerCompiler() та intlayerProxy() залишаються експортованими для складних налаштувань. Реєстрація їх разом з intlayer() безпечна — кожен плагін автоматично дедублює себе і запускається лише один раз.

Компілятор вимкнено за замовчуванням

Починаючи з Intlayer v9, компілятор вимкнено за замовчуванням (значення compiler.enabled тепер за замовчуванням дорівнює false). Щоб увімкнути вилучення ваших файлів .content.ts під час збірки, встановіть compiler.enabled: true у своїй конфігурації:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // За замовчуванням: false — потрібно для увімкнення компілятора починаючи з v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

Коли компілятор вимкнено, Intlayer пропускає крок вилучення під час збірки та покладається на вже оголошені вами словники. Вмикайте його лише тоді, коли хочете, щоб плагін збирача (@intlayer/swc, @intlayer/babel або Vite-плагін intlayer()) вилучав вміст автоматично.

React Native: імпорт з одного пакета

У програмі React Native або Expo вам більше не потрібно жонглювати react-intlayer та react-native-intlayer. Пакет react-native-intlayer тепер реекспортує весь API react-intlayer (хуки, утиліти та підшляхи /format, /html і /markdown), а його IntlayerProvider автоматично застосовує поліфіли React Native.

Імпортуйте все з єдиного пакета react-native-intlayer:

import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";

npm install intlayer react-native-intlayer

Імпорт з react-intlayer продовжує працювати, але react-native-intlayer тепер є рекомендованою єдиною точкою входу для React Native — його провайдер містить поліфіли, яких не має веб-орієнтований провайдер react-intlayer.

CMS SDK: використовуйте Intlayer як headless базу даних контенту

Intlayer v9 містить акуратний SDK з автоматичною автентифікацією в @intlayer/api для програмної взаємодії з CMS — отримувати проєкти, отримувати словники, а також надсилати чи оновлювати їх із власного сервера, скриптів або CI. Автентифікація (OAuth2 client_credentials) виконується та оновлюється за вас.

SDK розділено на два окремі імпорти, тож ваш бандл містить лише ті домени, які ви справді використовуєте:

1. createIntlayerCMS — легкий автентифікатор, який зберігає облікові дані та керований токен (клієнти доменів не включаються).
2. dictionaryEndpoint, projectEndpoint, … — прив'язки ендпоінтів для кожного домену, кожна імпортується зі свого підшляху.

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// Конфігурація необов'язкова: облікові дані беруться з INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET, що розв'язуються через `@intlayer/config/built`.const cms = createIntlayerCMS();// Читанняconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Запис — використовуйте CMS як базу данихawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Безпека: облікові дані CMS надають доступ до запису вашого контенту. Завжди створюйте автентифікатор лише на стороні сервера — ніколи не передавайте clientId / clientSecret у браузер.

Самостійне розгортання (Self-Hosting)

Intlayer v9 постачається з першокласною підтримкою запуску власного екземпляра Intlayer однією командою — обліковий запис Intlayer Cloud не потрібен.

curl -fsSL https://intlayer.org/install.sh | sh

Встановлювач завантажує docker-compose.yml та .env, автоматично генерує необхідні секрети та запускає docker compose up -d. Все — дашборд, API, база даних, сховище об'єктів та транзакційна електронна пошта — працює локально у контейнерах.

Включені сервіси

Chromium (що використовується для генерації знімків екрана через Puppeteer) вбудований у образ бекенду — додатковий контейнер не потрібен.

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

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

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

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

• Посібник з пакетів адаптерів сумісності (Compat Adapter Packages)
• Динамічні словники - Collections та Variants
• Довідник з конфігурації
• CMS SDK — програмний доступ через @intlayer/api
• Посібник із самостійного розгортання