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.).

Poniższa tabela wymienia je w wymaganej kolejności potoku (tej samej, w jakiej muszą wystąpić w babel.config.js):

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.

Wtyczka SWC (@intlayer/swc)

Użytkownicy Next.js również nigdy nie konfigurują tego bezpośrednio. Od wersji 9.2.1 withIntlayer() w next.config.ts uruchamia cały potok — purge, minifikację i przepisywanie importów — wyłącznie na podstawie flag build.purge i build.minify.

Praca jest podzielona na dwie części, ponieważ wtyczka Wasm SWC przekształca jeden plik naraz i nie ma dostępu do systemu plików:

Ustalenie, które pola są nieużywane i jaki alias otrzyma każde z nich, wymaga stanu obejmującego wiele plików oraz operacji wejścia/wyjścia na plikach, więc ta połowa działa w Node; wtyczka SWC otrzymuje jedynie wynikowe tablice.

Konfiguracja wg Platformy

npm install -D @intlayer/swc

[dependencies]
intlayer-swc-plugin = "*"

import { withIntlayer } from "next-intlayer/server";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {/* twoja konfiguracja */};

export default withIntlayer(nextConfig);

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // usuwa nieużywane pola treści z dołączonego JSON-a
    minify: true, // zmienia klucze pól treści na krótkie aliasy
  },
};

export default config;

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;

Minifikacja jest pomijana, gdy optimize ma wartość false. Gdy editor.enabled ma wartość true, nadal działa, ale bez etapu zmiany nazw pól — wizualny edytor odwzorowuje edycje za pomocą keyPath, więc oryginalne nazwy pól muszą zostać zachowane.

W Next.js minifikacja jest również pomijana, gdy @intlayer/swc nie jest zainstalowany albo nie może zostać załadowany (Next.js poniżej 16.1.0). Wtyczka to ta połowa, która przepisuje odwołania w kodzie źródłowym, więc zmiana nazw w słownikach bez niej pozostawiłaby kod odczytujący nazwy pól, które już nie istnieją.

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": "…" }

Purge jest pomijany, gdy optimize ma wartość false. Pozostaje aktywny, gdy editor.enabled ma wartość true — usunięte pole nie jest odczytywane przez żaden komponent, więc edytor nigdy go nie renderuje. W Next.js jest dodatkowo pomijany, gdy @intlayer/swc jest niedostępny oraz gdy skonfigurowano wywołujących z adapterów kompatybilności.

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órcy
const 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ści
const 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łania
const 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 zoptymalizowaniem
const content = useIntlayer("my-key");

// Powołany wynikowy tryb od zoptymalizowania Fetch'em
const 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