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.

Spis treści

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 (build time) 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.

Automatyczne formatowanie kodu: konfiguracja formatCommand

v7 wprowadza opcję formatCommand w konfiguracji edytora, pozwalającą na automatyczne formatowanie plików zawartości podczas ich zapisywania przez Intlayer. Zapewnia to spójny styl kodu i formatowanie we wszystkich plikach deklaracji zawartości.

Jeśli nie jest ustawiony, Intlayer spróbuje automatycznie wykryć polecenie formatowania. Próbując rozwiązać następujące polecenia: prettier, biome, eslint.

Konfiguracja

Opcja formatCommand akceptuje szablon ciągu znaków, w którym {{file}} zostanie zastąpiony rzeczywistą ścieżką pliku:

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

Obsługiwane formatory

Możesz używać dowolnego formatera kodu, który akceptuje ścieżki plików jako argumenty:

Używając Biome:

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

Używając Prettier:

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

Używając ESLint:

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

Używając wbudowanego formatera Bun:

formatCommand: 'bun format "{{file}}"';

Korzyści

• Spójne formatowanie: Wszystkie pliki zawartości są automatycznie formatowane zgodnie z wytycznymi stylu Twojego projektu
• Doświadczenie deweloperskie: Nie ma potrzeby ręcznego formatowania plików po ich wygenerowaniu przez Intlayer
• Spójność zespołu: Zapewnia, że wszyscy członkowie zespołu mają zastosowane to samo formatowanie do plików zawartości
• Integracja CI/CD: Pliki zawartości zachowują spójne formatowanie w zautomatyzowanych przepływach pracy

Jak to działa

Gdy Intlayer zapisuje lub aktualizuje plik deklaracji zawartości (.content.ts, .content.js, itp.), automatycznie uruchamia określone polecenie formatowania na pliku. Symbol zastępczy {{file}} jest zastępowany rzeczywistą ścieżką pliku, a polecenie jest wykonywane w katalogu bazowym projektu.

Konfiguracja Dictionary: Lepsza organizacja i struktura

v7 wprowadza nową dedykowaną sekcję konfiguracji dictionary, która zapewnia lepszą organizację ustawień związanych ze słownikiem i ulepszone zarządzanie zawartością.

Nowa struktura konfiguracji słownika

Właściwość fill została przeniesiona z sekcji content do nowej sekcji dictionary, zapewniając wyraźniejsze rozdzielenie odpowiedzialności:

Konfiguracja v6:

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

Konfiguracja v7:

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

Korzyści nowej struktury

• Wyraźniejsza organizacja: Ustawienia specyficzne dla słownika są teraz pogrupowane
• Lepsza separacja obaw: Odkrywanie zawartości a operacje na słowniku są wyraźnie rozdzielone
• Ulepszona łatwość utrzymania: Łatwiej zrozumieć i modyfikować konfiguracje związane ze słownikami
• Przyszła rozszerzalność: Sekcja słownika może zawierać dodatkowe ustawienia specyficzne dla słownika
• Kompleksowe zarządzanie słownikami: Obejmuje właściwości takie jak title, live, priority, tags, version i description do tworzenia i zarządzania nowymi słownikami

Użycie konfiguracji

Konfiguracja słownika służy dwóm głównym celom:

1. Wartości domyślne: Definiowanie wartości domyślnych podczas tworzenia plików deklaracji treści
2. Zachowanie fallbacku: Dostarczanie wartości fallbacku, gdy określone pola nie są zdefiniowane, umożliwiając globalną definicję zachowania operacji słownika

Sekcja słownika zawiera kompleksowe właściwości do zarządzania słownikiem:

• fill: Zachowanie auto-fill dla generowania treści
• title: Domyślny tytuł dla nowych słowników
• live: Konfiguracja live sync dla aktualizacji w czasie rzeczywistym
• priority: Ustawienia priorytetu dla rozdzielczości słownika
• tags: Domyślne tagi do organizacji treści
• version: Zarządzanie wersjami dla aktualizacji słownika
• description: Domyślny opis dla nowej treści

Aby uzyskać więcej informacji o plikach deklaracji treści i sposobie zastosowania wartości konfiguracji, zobacz Dokumentację pliku treści.

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

Nowe konfiguracje

• editor.formatCommand: Nowa opcja do automatycznego formatowania kodu plików zawartości

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