Optimierung der i18n-Bundle-Größe & Leistung

Eine der häufigsten Herausforderungen bei traditionellen i18n-Lösungen, die auf JSON-Dateien basieren, ist die Verwaltung der Inhaltsgröße. Wenn Entwickler den Inhalt nicht manuell in Namespaces trennen, laden Benutzer oft Übersetzungen für jede Seite und möglicherweise jede Sprache herunter, nur um eine einzige Seite anzuzeigen.

Beispielsweise könnte eine Anwendung mit 10 Seiten, die in 10 Sprachen übersetzt sind, dazu führen, dass ein Benutzer den Inhalt von 100 Seiten herunterlädt, obwohl er nur eine (die aktuelle Seite in der aktuellen Sprache) benötigt. Dies führt zu verschwendeter Bandbreite und langsameren Ladezeiten.

Intlayer löst dieses Problem durch Optimierung zur Build-Zeit. Es analysiert Ihren Code, um zu erkennen, welche Wörterbücher pro Komponente tatsächlich verwendet werden, und fügt nur den notwendigen Inhalt in Ihr Bundle ein.

Inhaltsverzeichnis

Analysieren Sie Ihr Bundle

Die Analyse Ihres Bundles ist der erste Schritt zur Identifizierung "schwerer" JSON-Dateien und Möglichkeiten zum Code-Splitting. Diese Tools generieren eine visuelle Treemap des kompilierten Codes Ihrer Anwendung, sodass Sie genau sehen können, welche Bibliotheken den meisten Platz beanspruchen.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";
import { visualizer } from "rollup-plugin-visualizer";

export default defineConfig({
  plugins: [
    visualizer({
      open: true, // Öffnet den Bericht automatisch in Ihrem Browser
      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({
  // Ihre Next.js Konfiguration
});

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,
    }),
  ],
};

Wie es funktioniert

Intlayer verwendet einen pro-Komponente-Ansatz. Im Gegensatz zu globalen JSON-Dateien wird Ihr Inhalt neben oder in Ihren Komponenten definiert. Während des Build-Prozesses führt Intlayer Folgendes aus:

1. Analysiert Ihren Code, um useIntlayer-Aufrufe zu finden.
2. Baut den entsprechenden Wörterbuchinhalt auf.
3. Ersetzt den useIntlayer-Aufruf durch optimierten Code basierend auf Ihrer Konfiguration.

Dies stellt sicher, dass:

• Wenn eine Komponente nicht importiert wird, deren Inhalt nicht im Bundle enthalten ist (Dead Code Elimination).
• Wenn eine Komponente verzögert geladen wird (lazy loaded), ihr Inhalt ebenfalls verzögert geladen wird.

Plugin-Referenz

Die Build-Optimierung von Intlayer ist auf mehrere diskrete Plugins aufgeteilt, von denen jedes eine einzige Aufgabe hat. Zu verstehen, was jedes Plugin tut, verhindert Verwirrung beim Einrichten.

Babel Plugins (@intlayer/babel)

Diese werden direkt in der babel.config.js für Webpack-basierte Setups verwendet (Next.js mit Babel, CRA, benutzerdefiniertes Webpack usw.).

Die folgende Tabelle listet sie in der erforderlichen Pipeline-Reihenfolge auf (dieselbe Reihenfolge, in der sie in babel.config.js erscheinen müssen):

Die Reihenfolge der Plugins ist wichtig. In Ihrer babel.config.js müssen das Purge- und Minify-Plugin vor dem Optimize-Plugin aufgeführt sein. Der Optimize-Pass ersetzt useIntlayer('key') durch einen undurchsichtigen useDictionary(hash)-Aufruf, wodurch die Information über den Wörterbuchschlüssel gelöscht wird, die der Purge- und Minify-Pass benötigen, um zu identifizieren, welche Felder verwendet werden.

Jedes Babel-Plugin verfügt über einen entsprechenden Options-Helfer, der Ihre intlayer.config.ts einmal zur Konfigurationsladezeit liest und vorab aufgelöste Werte zurückgibt:

Vite Plugins (vite-intlayer)

Vite-Benutzer konfigurieren diese nie direkt. Sie werden automatisch eingerichtet, wenn Sie withIntlayer() in der vite.config.ts aufrufen. Die Flags build.purge und build.minify in der intlayer.config.ts schalten das entsprechende Verhalten ohne zusätzliche Plugin-Registrierung um.

SWC-Plugin (@intlayer/swc)

Auch Next.js-Nutzer konfigurieren diese nie direkt. Seit v9.2.1 führt withIntlayer() in next.config.ts die vollständige Pipeline aus — Purge, Minify und Import-Umschreibung — allein anhand der Flags build.purge und build.minify.

Die Arbeit ist zweigeteilt, denn ein SWC-Wasm-Plugin transformiert jeweils nur eine Datei und hat keinen Dateisystemzugriff:

Zu entscheiden, welche Felder ungenutzt sind und welchen Alias jedes erhält, erfordert dateiübergreifenden Zustand und Datei-I/O; diese Hälfte läuft daher in Node, und das SWC-Plugin erhält nur die resultierenden Tabellen.

Setup nach Plattform

npm install -D @intlayer/swc

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

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

const nextConfig: NextConfig = {/* Ihre Konfiguration */};

export default withIntlayer(nextConfig);

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // entfernt ungenutzte Inhaltsfelder aus dem gebündelten JSON
    minify: true, // benennt Inhaltsfeldschlüssel in kurze Aliase um
  },
};

export default config;

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // Entfernt nicht verwendete Inhaltsfelder aus gebündelten JSONs
    minify: true, // Benennt Inhaltsfeld-Schlüssel in kurze Aliase um
  },
};

export default config;

npm install -D @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerPurgeBabelPlugin,
  intlayerMinifyBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getPurgePluginOptions,
  getMinifyPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  plugins: [
    // Extract: kompiliert .content.ts Dateien → .intlayer/**/*.json
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],

    // Purge: entfernt nicht verwendete Felder aus .intlayer/**/*.json
    //    (liest das Flag build.purge aus intlayer.config.ts)
    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],

    // Minify: benennt Feld-Schlüssel in JSON + Quellcode um
    //    (liest das Flag build.minify aus intlayer.config.ts)
    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],

    // Optimize: schreibt useIntlayer('key') → useDictionary(hash) um
    //    Muss zuletzt stehen, da es den Wörterbuchschlüssel löscht.
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

Konfiguration

Sie können steuern, wie Intlayer Ihr Bundle optimiert, über die Eigenschaft build in Ihrer intlayer.config.ts.

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.GERMAN],
    defaultLocale: Locales.ENGLISH,
  },
  dictionary: {
    importMode: "dynamic",
  },
  build: {
    // Ersetzt useIntlayer() Aufrufe zur Build-Zeit durch direkte Wörterbuch-Importe.
    // undefined = auto (aktiviert in der Produktion), true = immer, false = nie.
    optimize: undefined,

    // Benennt Inhaltsfeld-Schlüssel in kompilierten Wörterbüchern in kurze alphabetische
    // Aliase um (z.B. title → a). Reduziert die JSON-Größe; erfordert optimize.
    minify: true,

    // Entfernt Inhaltsfelder, die im Quellcode nie aufgerufen werden.
    // Erfordert optimize.
    purge: true,
  },
};

export default config;

Es wird empfohlen, in den meisten Fällen den Standardwert (undefined) für optimize beizubehalten.

Siehe die Konferenzreferenz für alle Optionen: Konfiguration

Build-Optionen

Minifizierung (Feld-Schlüssel-Umbennung)

build.minify verkleinert nicht Ihr JavaScript-Bundle — das erledigt Ihr Bundler. Stattdessen schrumpft es die kompilierten Wörterbuch-JSON-Dateien, indem jeder benutzerdefinierte Inhaltsfeld-Schlüssel durch einen kurzen alphabetischen Alias ersetzt wird:

// Vor der Minifizierung
{ "title": "Hallo", "subtitle": "Welt" }

// Nach der Minifizierung
{ "a": "Hallo", "b": "Welt" }

Dieselbe Umbenennung wird auf alle Eigenschaftszugriffe in Ihrem Quellcode angewendet, sodass content.title in der kompilierten Ausgabe zu content.a wird. Das Verhalten zur Laufzeit bleibt identisch.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    minify: true,
  },
};

export default config;

Die Minifizierung wird übersprungen, wenn optimize auf false gesetzt ist. Wenn editor.enabled auf true steht, läuft sie weiterhin, jedoch ohne den Schritt zur Feldumbenennung — der visuelle Editor löst Bearbeitungen über keyPath auf, daher müssen die ursprünglichen Feldnamen erhalten bleiben.

Unter Next.js wird die Minifizierung außerdem übersprungen, wenn @intlayer/swc nicht installiert ist oder nicht geladen werden kann (Next.js unterhalb von 16.1.0). Das Plugin ist die Hälfte, die die Quellcode-Zugriffe umschreibt; die Wörterbücher ohne es umzubenennen, würde Ihren Code Feldnamen lesen lassen, die es nicht mehr gibt.

Die Minifizierung wird ebenfalls für Wörterbücher übersprungen, die über importMode: 'fetch' geladen werden, da deren JSON von einer Remote-API mit den ursprünglichen Feldnamen bereitgestellt wird — das Umbenennen der clientseitigen Schlüssel würde den Server/Client-Vertrag brechen.

Purging (Entfernen ungenutzter Felder)

build.purge analysiert, auf welche Inhaltsfelder in Ihrem Quellcode tatsächlich zugegriffen wird, und entfernt alle anderen aus den kompilierten JSON-Dateien.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true,
  },
};

export default config;

Beispiel: Ein Wörterbuch mit fünf Feldern, von denen nur zwei verwendet werden:

// Vor dem Purge
{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }

// Nach dem Purge (nur auf title + subtitle wird im Quellcode zugegriffen)
{ "title": "…", "subtitle": "…" }

Der Purge wird übersprungen, wenn optimize auf false gesetzt ist. Er bleibt aktiv, wenn editor.enabled auf true steht — ein bereinigtes Feld wird von keiner Komponente gelesen, daher rendert der Editor es nie. Unter Next.js wird er zusätzlich übersprungen, wenn @intlayer/swc nicht verfügbar ist und wenn Kompatibilitäts-Adapter-Aufrufer konfiguriert sind.

Der Purge wird auch konservativ übersprungen, wenn eine Quelldatei nicht analysiert werden kann, oder wenn das Ergebnis von useIntlayer einer Variablen zugewiesen und auf eine Weise weitergegeben wird, die der statische Analysator nicht verfolgen kann (z.B. in ein Objekt eingefügt oder als Prop ohne Destrukturierung übergeben). In diesen Fällen wird das gesamte Wörterbuch beibehalten.

Import-Modus

Für große Anwendungen, die mehrere Seiten und Sprachen umfassen, kann das JSON einen erheblichen Teil der Größe Ihres Bundles ausmachen. Intlayer ermöglicht es Ihnen zu steuern, wie Wörterbücher mit der importMode-Option geladen werden.

Globale Definition

Der Import-Modus kann global in Ihrer intlayer.config.ts-Datei definiert werden.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  dictionary: {
    importMode: "dynamic", // Standard ist 'static'
  },
};

export default config;

Pro-Wörterbuch-Definition

Sie können den Import-Modus für einzelne Wörterbücher in deren .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}}-Dateien überschreiben.

import { type Dictionary, t } from "intlayer";

const appContent: Dictionary = {
  key: "app",
  importMode: "dynamic", // Überschreibt den standardmäßigen Import-Modus
  content: {
    // ...
  },
};

export default appContent;

Die Einstellung importMode bestimmt, wie der Wörterbuchinhalt in Ihre Komponente eingefügt wird. Sie können dies global in der intlayer.config.ts unter dem Objekt dictionary definieren oder für jedes Wörterbuch einzeln in dessen .content.ts-Datei überschreiben.

1. Statischer Modus (default)

Im statischen Modus ersetzt Intlayer useIntlayer durch useDictionary und injiziert das Wörterbuch direkt ins JavaScript-Bundle.

• Vorteile: Sofortiges Rendering (synchron), keine zusätzlichen Netzwerkanfragen während der Hydratation.
• Nachteile: Das Bundle enthält Übersetzungen für alle verfügbaren Sprachen für diese spezifische Komponente.
• Am besten für: Single Page Applications (SPA).

Beispiel für transformierten Code:

// Ihr Code
const content = useIntlayer("my-key");

// Veranschaulichung des optimierten Codes nach der Transformation (Statisch)
// Dies dient nur zur Veranschaulichung, der tatsächliche Code unterscheidet sich aus Optimierungsgründen
const content = useDictionary({
  key: "my-key",
  content: {
    nodeType: "translation",
    translation: {
      en: "My title",
      de: "Mein Titel",
    },
  },
});

2. Dynamischer Modus

Im dynamischen Modus ersetzt Intlayer useIntlayer durch useDictionaryAsync. Dies verwendet import() (ähnlich dem Suspense-Mechanismus), um spezifisch das JSON für die aktuelle Sprache verzögert zu laden.

• Vorteile: Tree Shaking auf Länderebene. Ein Benutzer, der die englische Version ansieht, wird nur das englische Wörterbuch herunterladen. Das deutsche Wörterbuch wird nie geladen.
• Nachteile: Löst eine Netzwerkanfrage (Asset-Abruf) pro Komponente während der Hydratation aus.
• Am besten für: Große Textblöcke, Artikel oder Anwendungen, die viele Sprachen unterstützen, bei denen die Bundle-Größe entscheidend ist.

Beispiel für transformierten Code:

// Ihr Code
const content = useIntlayer("my-key");

// Veranschaulichung des optimierten Codes nach der Transformation (Dynamisch)
// Dies dient nur zur Veranschaulichung, der tatsächliche Code unterscheidet sich aus Optimierungsgründen
const content = useDictionaryAsync({
  en: () =>
    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
      (mod) => mod.default
    ),
  de: () =>
    import(".intlayer/dynamic_dictionary/my-key/de.json").then(
      (mod) => mod.default
    ),
});

Wenn Sie importMode: 'dynamic' verwenden und auf einer einzigen Seite 100 Komponenten haben, die useIntlayer aufrufen, versucht der Browser, 100 separate Abrufe durchzuführen. Um diese "Wasserfall"-Anfragen zu vermeiden, gruppieren Sie Inhalte in weniger .content-Dateien (z.B. ein Wörterbuch pro Seitenabschnitt) anstatt in eines pro Atom-Komponente. Sie können auch mehrere .content-Dateien mit demselben Schlüssel verwenden. Intlayer wird sie dann zu einem einzigen Wörterbuch zusammenführen.

3. Fetch-Modus

Verhält sich ähnlich wie der dynamische Modus, versucht jedoch zuerst, Wörterbücher von der Intlayer Live Sync API abzurufen. Wenn der API-Aufruf fehlschlägt oder der Inhalt nicht für Live-Updates markiert ist, wird auf den dynamischen Import zurückgegriffen.

Beispiel für transformierten Code:

// Ihr Code
const content = useIntlayer("my-key");

// Veranschaulichung des optimierten Codes (Fetch)
const content = useDictionaryAsync({
  en: () =>
    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>
      res.json()
    ),
  de: () =>
    fetch("https://intlayer.my-domain.com/dictionary/my-key/de").then((res) =>
      res.json()
    ),
});

Weitere Details finden Sie in der CMS-Dokumentation: CMS

Im Fetch-Modus werden Purge und Minifizierung nicht angewendet, da das JSON von einer Remote-API mit den ursprünglichen Feldnamen bereitgestellt wird.

Zusammenfassung: Statisch vs Dynamisch