Nowy Intlayer v7 - Co nowego?

Witamy w Intlayer v7! To duże wydanie wprowadza znaczące ulepszenia w wydajności, bezpieczeństwie typów oraz doświadczeniu deweloperskim. Poniżej znajdują się najważniejsze zmiany, wraz z notatkami migracyjnymi i praktycznymi przykładami.

Najważniejsze zmiany

• Strategia buforowania dla szybszych kompilacji
• Ulepszone generowanie typów TypeScript z typami specyficznymi dla lokalizacji
• Optymalizacja pakietu: lokalizacje jako łańcuchy znaków zamiast enumów
• Nowe tryby routingu: prefix-no-default, prefix-all, no-prefix, search-params
• Przechowywanie lokalizacji zgodne z RODO, domyślnie w localStorage
• Elastyczna konfiguracja przechowywania: cookies, localStorage, sessionStorage lub wiele jednocześnie
• Pakiet Visual Editor mniejszy o 30%
• Rozszerzone opcje konfiguracji middleware
• Zaktualizowane zachowanie polecenia fill dla lepszego zarządzania treścią
• Zwiększona stabilność dzięki pełnym aktualizacjom plików deklaracji treści
• Inteligentne zarządzanie ponownymi próbami dla dokładności tłumaczeń
• Równoległe przetwarzanie dla szybszej obsługi tłumaczeń
• Inteligentne dzielenie na fragmenty, aby obsłużyć duże pliki w ramach limitów kontekstu AI

Wydajność: Caching dla szybszych kompilacji

Zamiast przebudowywać deklaracje treści za pomocą esbuild przy każdym buildzie, wersja 7 wprowadza strategię cache’owania, która przyspiesza proces budowania.

npx intlayer build

Nowy system cache’owania:

• Przechowuje skompilowane deklaracje treści, aby uniknąć zbędnego przetwarzania
• Wykrywa zmiany i przebudowuje tylko zmodyfikowane pliki
• Znacząco skraca czas budowania dużych projektów

TypeScript: Generowanie typów specyficznych dla lokalizacji

Typy TypeScript są teraz generowane dla każdej lokalizacji osobno, co zapewnia silniejsze typowanie i eliminuje typy unii obejmujące wszystkie lokalizacje.

Zachowanie w wersji 6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Zachowanie w wersji 7:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Korzyści:

• Bardziej precyzyjne podpowiedzi w Twoim IDE
• Lepsze bezpieczeństwo typów bez zanieczyszczenia typów między lokalizacjami
• Poprawiona wydajność dzięki zmniejszeniu złożoności typów

Optymalizacja bundla: Lokalizacje jako stringi

Typ Locales nie jest już enumeracją, co oznacza, że jest teraz w pełni możliwy do tree-shakingu i nie będzie powiększał Twojego bundla o tysiące nieużywanych rekordów lokalizacji.

v6:

import { Locales } from "intlayer";// Enum zawierający wszystkie lokalizacje -> nie jest możliwy do tree-shakinguconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Typ string -> w pełni możliwy do tree-shakinguconst locale: Locale = Locales.ENGLISH;

Ponieważ Locales nie jest już enumeracją, będziesz musiał zmienić typ z Locales na Locale, aby uzyskać lokalizację jako typ.

Zobacz szczegóły implementacji po więcej informacji.

Nowe tryby routingu dla większej elastyczności

Wersja v7 wprowadza zunifikowaną konfigurację routing.mode, która zastępuje poprzednie opcje prefixDefault i noPrefix, oferując bardziej szczegółową kontrolę nad strukturą URL.

Dostępne tryby routingu

• prefix-no-default (domyślny): Domyślna lokalizacja nie ma prefiksu, inne lokalizacje mają
  • /dashboard (en) lub /fr/dashboard (fr)
• prefix-all: Wszystkie lokalizacje mają prefiks
  • /en/dashboard (en) lub /fr/dashboard (fr)
• no-prefix: Brak prefiksów lokalizacji w URL (lokalizacja obsługiwana przez storage/headers)
  • /dashboard dla wszystkich lokalizacji
• search-params: Lokalizacja przekazywana jako parametr zapytania
  • /dashboard?locale=en lub /dashboard?locale=fr

Podstawowa konfiguracja

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // domyślnie  },};

Zgodność z RODO: storage w localStorage / cookies

Wersja v7 stawia na prywatność użytkownika, używając localStorage jako domyślnego mechanizmu przechowywania zamiast cookies. Ta zmiana pomaga w zgodności z RODO, unikając wymagań dotyczących zgody na cookies dla preferencji lokalizacji.

Opcje konfiguracji storage

Nowe pole routing.storage jest również dostępne oprócz wcześniejszych opcji middleware.cookieName i middleware.serverSetCookie, oferując elastyczne konfiguracje przechowywania:

// Wyłącz przechowywaniestorage: false// Proste typy przechowywaniastorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie z niestandardowymi atrybutamistorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage z niestandardowym kluczemstorage: {  type: 'localStorage',  name: 'custom-locale'}// Wiele typów przechowywania dla redundancjistorage: ['cookie', 'localStorage']

Przykład konfiguracji zgodnej z RODO

Dla aplikacji produkcyjnych, które muszą wyważyć funkcjonalność z zgodnością z RODO:

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Główne przechowywanie (nie wymaga zgody)        name: "user-locale",      },      {        type: "cookie", // Opcjonalne przechowywanie w ciasteczkach (wymaga zgody)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Włączanie / wyłączanie przechowywania w ciasteczkach

Przykład użycia w React / Next.js:

Można zdefiniować globalnie:

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

Można nadpisać lokalnie dla każdego hooka:

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

Uwaga: Cookies są domyślnie włączone. Uwaga: Sprawdź wymagania dotyczące plików cookie zgodne z RODO dla swojego konkretnego przypadku użycia.

Edytor wizualny: pakiet o 30% mniejszy

Pakiet Edytora wizualnego został zoptymalizowany i jest o 30% mniejszy niż poprzednia wersja, dzięki:

• Poprawie wydajności edytora kodu
• Usunięciu niepotrzebnych zależności od pakietów rdzenia Intlayer
• Lepszemu tree-shakingowi i bundlowaniu modułów

Skutkuje to szybszym czasem pobierania i lepszą wydajnością działania Twojej aplikacji.

Komenda fill: Zaktualizowane zachowanie dla lepszego zarządzania treścią

Wersja 7 wprowadza ulepszone zachowanie komendy fill, zapewniając bardziej przewidywalne i elastyczne zarządzanie treścią:

Nowe zachowanie polecenia fill

• fill: true - Nadpisuje bieżący plik wypełnioną zawartością dla wszystkich lokalizacji
• fill: "ścieżka/do/pliku" - Wypełnia określony plik bez modyfikowania bieżącego pliku
• fill: false - Całkowicie wyłącza automatyczne wypełnianie

Ulepszone wsparcie dla złożonych struktur zawartości

Polecenie fill obsługuje teraz złożone struktury deklaracji zawartości, w tym:

• Obiekty złożone: Deklaracje zawartości, które odwołują się do innych obiektów
• Zawartość destrukturyzowana: Zawartość wykorzystująca wzorce destrukturyzacji
• Zagnieżdżone odwołania: Obiekty wywołujące się nawzajem w złożonych hierarchiach
• Dynamiczne struktury zawartości: Zawartość z warunkowymi lub obliczanymi właściwościami

Korzyści

• Jasniejszy zamiar: Zachowanie jest teraz bardziej jednoznaczne co do tego, co jest modyfikowane
• Lepsze rozdzielenie: Pliki z zawartością mogą być przechowywane oddzielnie od wypełnionych tłumaczeń
• Ulepszony przepływ pracy: Deweloperzy mają większą kontrolę nad miejscem przechowywania tłumaczeń
• Wsparcie dla złożonych struktur: Obsługa zaawansowanych architektur zawartości z wieloma powiązanymi obiektami

Przykład użycia

// Nadpisz bieżący plik wszystkimi lokalizacjamiconst content = {  key: "example",  fill: true, // Nadpisuje ten plik  content: {    title: "Hello World",  },};// Wypełnij osobny plik bez modyfikacji bieżącego plikuconst content = {  key: "example",  fill: "./translations.json", // Tworzy/aktualizuje translations.json  content: {    title: "Hello World",  },};// Wyłącz automatyczne wypełnianieconst content = {  key: "example",  fill: false, // Brak automatycznego wypełniania  content: {    title: "Hello World",  },};// Złożona struktura treści z obiektami złożonymiconst sharedContent = {  buttons: {    save: "Zapisz",    cancel: "Anuluj",  },};const content = {  key: "complex-example",  fill: true,  content: {    // Odwołania do innych obiektów    sharedContent,    // Rozpakowana zawartość    ...sharedContent,    // Zagnieżdżone odwołania    sections: [      {        ...sharedContent.buttons,        header: "Sekcja 1",      },    ],  },};

Zwiększona stabilność i zarządzanie tłumaczeniami

Wersja 7 wprowadza kilka usprawnień, które czynią tłumaczenie treści bardziej niezawodnym i efektywnym:

Pełne aktualizacje plików deklaracji treści

System teraz aktualizuje pliki .content.{ts,js,cjs,mjs} zamiast częściowych aktualizacji, co zapewnia:

• Integralność danych: Pełne przepisywanie plików zapobiega częściowym aktualizacjom, które mogłyby uszkodzić zawartość
• Spójność: Wszystkie lokalizacje są aktualizowane atomowo, co utrzymuje synchronizację
• Niezawodność: Zmniejsza ryzyko niekompletnych lub uszkodzonych plików zawartości

Inteligentne zarządzanie ponownymi próbami

Nowe mechanizmy ponownych prób zapobiegają przesyłaniu zawartości w niepoprawnych formatach i unikają przerwania całego procesu wypełniania, jeśli jedno żądanie się nie powiedzie.

Równoległość dla szybszego przetwarzania

Operacje tłumaczenia są teraz wykonywane w kolejce, aby uruchamiać je równolegle. Znacząco przyspiesza to proces.

Inteligentne dzielenie na fragmenty dla dużych plików

Zaawansowane strategie dzielenia na fragmenty radzą sobie z dużymi plikami zawartości, nie przekraczając limitów kontekstu AI:

Przykładowy przebieg pracy

// Duży plik zawartości jest automatycznie dzielony na fragmentyconst content = {  key: "large-documentation",  fill: true,  content: {    // Duża zawartość automatycznie dzielona na fragmenty do przetwarzania przez AI    introduction: "..." // ponad 5000 znaków    sections: [      // Wiele dużych sekcji    ]  }};

System automatycznie:

1. Analizuje rozmiar i strukturę zawartości
2. Odpowiednio dzieli zawartość na fragmenty
3. Przetwarza fragmenty równolegle
4. Waliduje i ponawia próby w razie potrzeby
5. Odtwarza kompletny plik

Notatki migracyjne z wersji v6

Usunięte konfiguracje

• middleware.cookieName: Zastąpione przez routing.storage
• middleware.serverSetCookie: Zastąpione przez routing.storage
• middleware.prefixDefault: Zastąpione przez routing.mode
• middleware.noPrefix: Zastąpione przez routing.mode

Mapowanie migracji

Mapowanie konfiguracji

Przykład migracji

Przed (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Po (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // lub 'cookie', jeśli potrzebujesz przechowywania w ciasteczkach    headerName: "x-intlayer-locale",    basePath: "",  },};

Mapowanie zawartości słownika

Przykład migracji

Przed (v6):

const content = {  key: "example",  autoFill: true, // Nadpisuje ten plik  content: {    title: "Hello World",  },};

Po (v7):

const content = {  key: "example",  fill: true, // Nadpisuje ten plik  content: {    title: "Hello World",  },};

Notatki dotyczące migracji z v5 do v6

Sprawdź notatki dotyczące migracji z v5 do v6 po więcej informacji.

Przydatne linki

• Referencja konfiguracji
• Dokumentacja Middleware
• Typy TypeScript
• Wytyczne dotyczące plików cookie zgodne z RODO