Nowy Intlayer v9 - Co nowego?

Witaj w Intlayer v9! To główne wydanie (major release) stanowi ogromny krok milowy w upraszczaniu ścieżki migracji do Intlayer dzięki pakietom kompatybilności (Compat Adapter Packages) dla najpopularniejszych bibliotek i18n (takich jak react-i18next, next-intl, vue-i18n itp.) oraz wprowadza wsparcie dla bogatych struktur treści: Kolekcji (Collections), Wariantów (Variants) i Dynamicznych Rekordów (Dynamic Records).

Spis treści

Pakiety kompatybilności (Compat Adapter Packages)

Migracja do Intlayer z popularnych bibliotek i18n jest teraz łatwiejsza niż kiedykolwiek. Stworzyliśmy pięć pakietów kompatybilności (compat packages), które udostępniają dokładnie to samo publiczne API co standardowe biblioteki i18n, ale delegują całą pracę związaną z tłumaczeniami do Intlayer w czasie działania aplikacji (runtime).

To samo publiczne API ze ścisłym typowaniem (Strict Typing)

Zastępując importy, zyskujesz wszystkie zalety Intlayer (w tym bezpieczeństwo typów w czasie kompilacji - compile-time type safety - w oparciu o Twoje rzeczywiste słowniki) przy minimalnych zmianach w kodzie:

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

Na przykład, po prostu zmień:

import { useTranslation } from "react-i18next";

na:

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

Twoje klucze będą teraz ściśle typowane (strictly typed) w oparciu o słowniki Intlayer, oferując pełne autouzupełnianie ścieżek kropkowych (dot-path) w Twoim IDE!

Pluginy aliasów dla bundlerów (Vite, Next.js, Turbopack)

Aby umożliwić migrację bez konieczności ręcznego przepisywania wszystkich importów, każdy pakiet adaptera kompatybilności zawiera dedykowany plugin dla bundlera (Vite lub Next.js) w podścieżce /plugin.

Pluginy te automatycznie przepisują istniejące importy (np. react-i18next lub next-intl) na ich odpowiedniki @intlayer/* w czasie budowania (build time).

Przykład dla Next.js (Webpack / Turbopack)

Zamiast withIntlayer, owiń swoją konfigurację Next.js pluginem kompatybilności:

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

Przykład dla Vite (React, Vue, Solid, Svelte)

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

Wspólny parser czasu działania (Mutualized Runtime Resolver)

Wszystkie adaptery kompatybilności kierują teraz proces rozwiązywania tłumaczeń przez jeden, wysoce zoptymalizowany parser czasu działania (runtime parser): @intlayer/core/messageFormat.

• Interpolacja wiadomości (Interpolate Message): Obsługuje standardowe szablony {{var}} (ze spacjami i ścieżkami kropkowymi), argumenty formatowane w standardzie ICU ({v, number, percent} itp.) oraz proste szablony {var}.
• Rozwiązywanie węzłów wiadomości (Message Node Resolver): Obsługuje zagnieżdżone węzły: insert(), plural() (reguły liczby mnogiej CLDR), enu() (wyliczenia), gender(), tagi HTML, tablice oraz węzły funkcji wywoływalnych (callable functions).
• Parser tagów tokenizowanych (Tokenized Tag Parser): Wspiera wbudowane tagi XML/HTML oraz tagi numerowane (np. <1>children</1>), aby zapewnić renderowanie bogatego tekstu (rich-text) po wyjęciu z pudełka.

Specyfikacja funkcji: Kolekcje, Warianty i Dynamiczne Rekordy

Intlayer v9 wykracza poza statyczne obiekty klucz-wartość, umożliwiając słownikom deklarowanie dynamicznych struktur układu, które są w pełni typowane od początku do końca (end-to-end).

1. Kolekcje (Collections)

Zdefiniuj zarządzaną przez CMS uporządkowaną lista elementów (np. FAQ, produkty lub listy blogów):

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  content: [    {      question: t({        pl: "Co to jest Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        pl: "Zestaw narzędzi i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

Użycie:

// Pobierz wszystkie elementyconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Pobierz pojedynczy element po indeksieconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. Warianty (Variants)

Dostarczaj testy A/B, nagłówki sezonowe, flagi funkcji (feature flags) lub niestandardowe strony docelowe (landing pages):

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ pl: "Witaj", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      pl: "Kup teraz",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

Użycie:

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

3. Dynamiczne Rekordy (Dynamic Records)

Definiuj słowniki, których wpisy są ładowane dynamicznie w czasie działania aplikacji (runtime) za pomocą identyfikatorów zapytań (query IDs):

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    id: "prod_123",    category: "books",  },  content: {    title: t({ pl: "Czysty kod", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

Użycie:

// Pobiera dynamicznie tylko żądany element (wymaga Suspense)const product = useIntlayer("product-copy", {  id: "prod_123",  category: "books",});

Dynamiczne ładowanie i optymalizacja rozmiaru paczki (Bundle Size)

Aby zachować niezwykle mały rozmiar paczek (bundles), Intlayer v9 wspiera dynamiczne leniwe ładowanie (lazy loading).

W swojej konfiguracji ustaw importMode na 'dynamic' lub 'fetch':

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

W czasie budowania (build time), @intlayer/swc oraz @intlayer/babel skanują Twoje pliki i zastępują wywołania useIntlayer / getIntlayer opakowaniami wspierającymi tree-shaking (useDictionary / useDictionaryDynamic). Ładowana jest tylko treść wymagana dla wybranego elementu kolekcji, wariantu lub języka (locale), co zapobiega dołączaniu nieużywanych tłumaczeń do Twojej paczki produkcyjnej (production bundle).

Uwagi dotyczące migracji z wersji v8

Jeśli aktualizujesz aplikację z wersji v8, pamiętaj, że wersja v9 nie zawiera zmian wprowadzających niekompatybilność wsteczną (breaking changes). Oto jednak kluczowe zmiany:

• Języki i dialekty (Locales & Dialects): Jeśli używasz zewnętrznych zależności i18n, dodaj odpowiednie pluginy adapterów kompatybilności w swojej konfiguracji lub konfiguracji bundlera, aby automatycznie przepisywać importy.
• Niestandardowe selektory (Custom Selectors): Podczas wywoływania useIntlayer, drugi parametr jest teraz zarezerwowany dla obiektu opcji zawierającego { locale, item, variant, id }. Jeśli wcześniej przekazywałeś bezpośrednio ciąg znaków języka (locale string), nadal możesz to robić, jednak zaleca się używanie obiektu opcji przy bardziej zaawansowanych wyborach.

Przydatne linki

• Przewodnik po pakietach kompatybilności (Compat Adapter Packages)
• Dynamiczne słowniki - Kolekcje, Warianty i Dynamiczne Rekordy
• Dokumentacja konfiguracji