Optymalizacja Rozmiaru Paczki i Wydajności i18n

Jednym z najczęstszych wyzwań w tradycyjnych rozwiązaniach i18n opartych na plikach JSON jest zarządzanie rozmiarem treści. Jeśli programiści nie rozdzielą treści na przestrzenie nazw (namespaces) ręcznie, użytkownicy często pobierają tłumaczenia dla każdej strony i potencjalnie każdego języka, tylko po to, aby wyświetlić pojedynczą stronę.

Na przykład, aplikacja z 10 stronami przetłumaczonymi na 10 języków może spowodować, że użytkownik pobierze zawartość 100 stron, chociaż potrzebuje tylko jednej (bieżącej strony w bieżącym języku). Prowadzi to do marnowania przepustowości i wolniejszego ładowania.

Intlayer rozwiązuje ten problem poprzez optymalizację w czasie budowania. Analizuje on Twój kod, aby wykryć, które słowniki są faktycznie używane w poszczególnych komponentach, i wprowadza do paczki (bundle) tylko niezbędne treści.

Spis Treści

Przeanalizuj swoją paczkę

Analiza paczki jest pierwszym krokiem do zidentyfikowania "ciężkich" plików JSON i możliwości dzielenia kodu (code-splitting). Narzędzia te generują wizualną mapę drzewa (treemap) skompilowanego kodu aplikacji, co pozwala precyzyjnie zobaczyć, które biblioteki zajmują najwięcej miejsca.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";import { visualizer } from "rollup-plugin-visualizer";export default defineConfig({ plugins: [   visualizer({     open: true, // Automatycznie otwórz raport w przeglądarce     filename: "stats.html",     gzipSize: true,     brotliSize: true,   }), ],});

npx next experimental-analyze

npm install -D @next/bundle-analyzer

const withBundleAnalyzer = require("@next/bundle-analyzer")({ enabled: process.env.ANALYZE === "true",});module.exports = withBundleAnalyzer({ // Twoja konfiguracja Next.js});

ANALYZE=true npm run build

npm install -D webpack-bundle-analyzer

import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";export default { plugins: [   new BundleAnalyzerPlugin({     analyzerMode: "static",     reportFilename: "bundle-analyzer.html",     openAnalyzer: false,   }), ],};

Jak to Działa

Intlayer wykorzystuje podejście per-komponent. W przeciwieństwie do globalnych plików JSON, Twoje treści są definiowane obok komponentów lub wewnątrz nich. Podczas procesu budowania Intlayer wykonuje następujące czynności:

1. Analizuje Twój kod w celu znalezienia wywołań funkcji useIntlayer.
2. Buduje treść odpowiednich słowników.
3. Zamienia wywołanie useIntlayer na zoptymalizowany kod, zgodnie z Twoją konfiguracją.

Gwarantuje to, że:

• Jeśli komponent nie zostanie zaimportowany, jego treść nie zostanie dołączona do paczki (Dead Code Elimination).
• Jeśli komponent ładuje się leniwie (lazy-loaded), jego zawartość również ładuje się w ten sam sposób.

Informacje o Wtyczkach

Optymalizacja w trakcie budowania przez Intlayer podzielona jest na kilka niezależnych wtyczek, z których każda odpowiada za jedno zadanie. Zrozumienie roli poszczególnych wtyczek zapobiegnie nieporozumieniom podczas ich konfiguracji.

Wtyczki Babel (@intlayer/babel)

Wtyczki te są wykorzystywane bezpośrednio w babel.config.js dla środowisk opartych na Webpacku (Next.js z Babel, CRA, własne konfiguracje Webpack itp.).

Kolejność wtyczek ma znaczenie. W Twoim babel.config.js wtyczki purge i minify muszą pojawić się przed wtyczką optimize. Krok optymalizacji zastępuje bowiem useIntlayer('key') nieprzejrzystym wywołaniem useDictionary(hash), usuwając informację o kluczu słownika. Właśnie tej informacji potrzebują etapy purge i minify, aby móc określić, które pola są wykorzystywane.

Każda z wtyczek dla Babel ma swój dedykowany helper dla opcji, który odczytuje intlayer.config.ts tylko raz (podczas wczytywania konfiguracji) i zwraca wstępnie rozwiązane wartości:

Wtyczki Vite (vite-intlayer)

Użytkownicy Vite nigdy nie konfigurują ich bezpośrednio. Są one podłączane automatycznie po wywołaniu withIntlayer() w pliku vite.config.ts. Flagi build.purge i build.minify umieszczone w intlayer.config.ts przełączają ich zachowanie bez potrzeby dodatkowego rejestrowania wtyczek.

Konfiguracja wg Platformy

npm install -D @intlayer/swc

npm install -D @intlayer/babel

const { intlayerPurgeBabelPlugin, intlayerMinifyBabelPlugin, getPurgePluginOptions, getMinifyPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Purge: usuwa nieużywane pola ze słowników z .intlayer/**/*.json   [intlayerPurgeBabelPlugin, getPurgePluginOptions()],   // Minify: skraca nazwy kluczy w polach w plikach JSON i kodzie źródłowym   [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],   // Uwaga: intlayerOptimizeBabelPlugin NIE JEST TUTAJ POTRZEBNY, ponieważ   // to @intlayer/swc obsługuje zastępowanie useIntlayer → useDictionary. ],};

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = { build: {   purge: true, // usuwa ze zgrubnych plików JSON te nieużywane pola treści   minify: true, // zmienia aliasy kluczy dla tychże pól treści w aliasy skróceniowe },};export default config;

npm install -D @intlayer/babel

const { intlayerExtractBabelPlugin, intlayerPurgeBabelPlugin, intlayerMinifyBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getPurgePluginOptions, getMinifyPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { plugins: [   // Extract: dokonuje kompilacji plików ze zbioru .content.ts → .intlayer/**/*.json   [intlayerExtractBabelPlugin, getExtractPluginOptions()],   // Purge: ucina niewykorzystane i zagubione przestrzenie w .intlayer/**/*.json   //    (wykorzystuje flagi odczytane uprzednio z intlayer.config.ts)   [intlayerPurgeBabelPlugin, getPurgePluginOptions()],   // Minify: zastępuje dotychczasowe klucze literowymi ich krótkimi skrótami   //    (wykorzystuje flagę pobraną pierwotnie z intlayer.config.ts)   [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],   // Optimize: nadpisuje strukturę składni formy useIntlayer('key') → useDictionary(hash)   //    Wymagane jest usytuowanie na samym końcu, bowiem kasuje powiązany oryginalny znak wywoławczy ze słownika.   [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};

Konfiguracja

Możesz kontrolować, w jaki sposób Intlayer optymalizuje Twoją paczkę poprzez propercję build w pliku intlayer.config.ts.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.POLISH],    defaultLocale: Locales.ENGLISH,  },  dictionary: {    importMode: "dynamic",  },  build: {    // Zamienia wywołania useIntlayer() na bezpośrednie importy ze słowników podczas budowania.    // undefined = auto (włączone w produkcji), true = zawsze, false = nigdy.    optimize: undefined,    // Zmienia długie nazwy kluczy dla pól we wkompilowanych słownikach na ich krótkie,    // jednoznakowe wersje alfabetyczne (np. title → a). Zmniejsza rozmiar pliku JSON; wymaga optymalizacji.    minify: true,    // Usuwa pola treści, do których kod źródłowy nie uzyskał w ogóle bezpośredniego dostępu.    // Wymaga zdefiniowania optimize w pliku konfiguracyjnym.    purge: true,  },};export default config;

Zaleca się na ogół pozostawienie wartości domyślnej (undefined) dla opcji optimize.

Zobacz referencje dotyczące samej konfiguracji po resztę opcji: Konfiguracja

Opcje Budowania

Minifikacja (Zmienianie Nazw Kluczy)

Opcja build.minify nie zminifikuje ogólnej zawartości Twojego JavaScript — tym zajmie się odpowiedni silnik bundlera. Jej wiodącym atutem jest to, iż potrafi znacznie skurczyć same przekształcone tablice opatrzone zwięzłym JSON o krótkie litery wygenerowanego alfabetu:

// Przed użyciem Minifikacji{ "title": "Witaj", "subtitle": "Świecie" }// Po zastosowaniu Minifikacji{ "a": "Witaj", "b": "Świecie" }

Podobnie powiela to swój udział na polu kodu źródłowego, aby w toku procesów budowlanych komenda pokroju content.title zamieniła się nieoczekiwanie w formę typu content.a zachowując idealny ekosystem bezbłędnej relacyjności.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    minify: true,  },};export default config;

Krok dla minifikacji musi zostać oddalony w odstawkę, gdy Twoja opcja to optimize lub jeżeli udostępniasz systemowo editor.enabled i ustawiasz na domyślne true (wymuszone jest, aby pola trzymały na ten czas swe niezmącone relacje, dla potrzeb odpowiedniego renderowania Wizualnego Edytora).

Ten sam manewr odłożenia ma miejsce w słownikach przywoływanych jako typ opcji z użyciem importMode: 'fetch', gdzie zawarte odpowiedzi napływają niezwłocznie dzięki połączonemu formatowi JSON. Gdyby zastosowano sztuczne przeinaczenie ze stron zewnętrznych, serwer stałby się bezużyteczny z perspektywy klienta i połącznie zostałoby połamane.

Purging (Usuwanie Nieużytych Przestrzeni)

Moduł oznaczający się słowem build.purge dba za to nad śledzeniem rzeczywistego obłożenia zawartych zmiennych i parametrów w paczkach JSON, ucinając puste lub zbyteczne zapytania.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    purge: true,  },};export default config;

Przykład: Jeden pospolity słownik wyposażony chociażby o cztery kluczowe pola niepotrzebnego balastu.

// Przed aktywacją "purge"{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }// Po jej zapoczątkowaniu, ostaną się wyłącznie title oraz np. subtitle, połączone więzami skryptu.{ "title": "…", "subtitle": "…" }

Mechanizm obalenia Purge opiera się głównie o pominięcia w wypadku kiedy brakuje optimize opcjonalnej flagi tudzież podczas zadeklarowania trybu pod system Visual Editor (ustawiając editor.enabled na rzecz trybu true).

Co rzadsze zjawiska również tyczą się tego obejścia - dla niemożności sprawdzenia wycinka czy pospolitych struktur dla useIntlayer - silnik bezbłędnie zablokuje akcję. Przykładowo dla wywołań w niejednoznacznych tablicach powiązanych metod bez destrukturyzacji by zachować słownikową formę naturalną.

Tryby Importowania Słownika

Dla zaawansowanych ekosystemów skategoryzowanych opcją mnogości języków i pokaźną objętościowo rzeszą podstron Twoje tablice JSON mogą mocno oddziaływać na bazowy wyciąg i jego rozmiar końcowy. Aplikując importMode możemy opanować zapytania pobraniowe by temu zapobiegać.

Globalne Zarządzanie Opcją

Możesz w zupełności operować trybem importowania globalnym parametrem skrytym pod przykrywką w Twoim nowym intlayer.config.ts.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  dictionary: {    importMode: "dynamic", // Wybranym trybem domyślnym staje się "static"  },};export default config;

Tryby w Indywidualnych Odłamach Słownikowych

Możesz ustrzec się opcji dla ogólnego użycia poprzez dopisywanie warunkowych ułożeń we wkompilowanych od siebie osobnych elementach .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}}.

import { type Dictionary, t } from "intlayer";const appContent: Dictionary = {  key: "app",  importMode: "dynamic", // Tutaj nadpiszemy dominujący import oparty domyślną strukturą.  content: {    // ...  },};export default appContent;

Opcja bazująca z formy poleceń pod szyldem importMode dyktuje polecenia operujące mechanikami w Twoim powiązanym komponencie. Może to wpłynąć na tryb globalny i wpisy ze zbiorów poszczególnych dla dictionary.

1. Tryb Zastosowań Statycznych (default)

W ramach trybu użytego dla form static Intlayer podmieni i przekształci naturalne skrótowce useIntlayer wykończonymi formułami słownymi od useDictionary, tym samym ładując bezpośrednio skompilowany ciąg zdarzeniowy.

• Korzyści: Ekspresowe podpięcie od zera. Bezpośrednia relacja nie odpytująca ponownych pobrań w asyście przy trybie nawadniania środowiskowego.
• Mankamenty: Podłączona pod aplikację końcową baza staje się mocno skondensowana. Pobierasz wszystkie dostępne klucze pakietów, ignorując aktualnie wymagane przez dany obszar wytyczne.
• Kiedy Najlepiej Zastosować: Systemy powiązane pod wariant tak zwanej Jednej Strony Aplikacji (SpA).

Przykład Transformacji Skryptowej:

// Skrypt Przykładowy Twórcyconst content = useIntlayer("my-key");// Tak prezentuje się optymalna struktura oparta pod Tryb (Statyczny)// Skrypt poglądowy odzwierciedla w pełni model bazowy i może wybiegać ze swoich skrajnościconst content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      pl: "Mój tytuł",    },  },});

2. Tryb Obiektowo Dynamiczny

Podejmując wyzwania trybu Dynamic, Intlayer operuje na zapleczu poleceń useDictionaryAsync, ignorując swego poprzednika by przenieść ciężar zapytania przez typ lazy z mechanizmem przypominającym środowisko import() uodparniając specyficznie wymogi dla pliku językowego pod pożądane żądanie lokalne z odpowiednim JSON.

• Korzyści: Skupienie na lokalizacji względem wagi i jej usunięciu (Tree-Shaking). Typowy entuzjasta spolszczonego wariantu otrzyma spójną i pożądaną wyłącznie tablicę z wgranym językiem. Inne wersje nie zostaną użyte dla odciążeń.
• Mankamenty: Aktywuje ułamek żądań na serwer, prosząc sieć o asystę podczas uwadniania strony.
• Kiedy Najlepiej Zastosować: Potężne objętości tekstu, opasłe publikacje tudzież platformy łączące setki państw z prężnym budżetem optymalizacyjnym pakietów.

Przykład Skompresowanego Zastosowania W Wyniku Zdarzeń:

// Przed rozpoczęciem działaniaconst content = useIntlayer("my-key");// Wizualizacja form po obrabianiu ze skryptem docelowym (Pamięciowy tryb dynamiczny)const content = useDictionaryAsync({  en: () =>    import(".intlayer/dynamic_dictionary/my-key/en.json").then(      (mod) => mod.default    ),  pl: () =>    import(".intlayer/dynamic_dictionary/my-key/pl.json").then(      (mod) => mod.default    ),});

Mając na karku włączone systemowe rozwiązanie ukierunkowane opcją pod importMode: 'dynamic', pamiętaj, że na jednej powiązanej karcie strony mającej np. ok 100 powiązanych żądań typu odniesieniowego i wzywających formułę useIntlayer strona posiłkująca się wybranym standardem wyleje żale w liczbie dokładnie tych samych 100 wywołań. Reaguj zawczasu. Postaraj się sprytnie redukować poszczególne tablice plikami np. ograniczając je w jedną, spójniejszą formułę typu podzbioru dla np. mniejszych wycinków danej strony. Istnieje opcja dodania atutów w postać nadpisywanych wycinków operujących nad tym samym imieniem, które w późniejszym etapie łączą wywołania w postać i strukturę połączonego spoiwa.

3. Zastosowania W Formule Fetch

Kolejny z bliźniaczych w budowie form importowania. Jego nieprzeniknione różnice to typowy pościg powiązany oparty od Live Sync API serwowanym wektorami we wrotach Intlayera, i gdyby napotkał się w trudzie awaryjnym (Błąd Odpowiedzi itd.) by przerzucić resztkę pod standard powiązań od swojego zapasowego formatu dynamicznych form podążających.

Twór Opracowany W Końcowej Generacji Na Poczet Zapytania Z Sieci:

// Początek skryptowania przed zoptymalizowaniemconst content = useIntlayer("my-key");// Powołany wynikowy tryb od zoptymalizowania Fetch'emconst content = useDictionaryAsync({  en: () =>    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>      res.json()    ),  pl: () =>    fetch("https://intlayer.my-domain.com/dictionary/my-key/pl").then((res) =>      res.json()    ),});

Zaglądnij do źródeł, jeżeli brakuje Tobie stosownej wiedzy operującej opcjami dla CMS: Rozwiązania Typu CMS

W środowisku opartym modelem o formy z API o parametrze fetch całkowicie ominięte obłożone procesy z grupy eliminowania (purge) i ukrywania z modyfikacjami optycznymi (minify) kluczy tablicy ulegają trwałemu przeistoczeniu, z powodem opartym m.in. użyciu zapytania przez wektor o relacje klucza zachowującego swoje parametry oryginału.

Tabelaryczne Oświadczenie - Statyczny oraz Formuła Dynamiki