Neues Intlayer v9 – Was ist neu?

Willkommen bei Intlayer v9! Dieses Major Release markiert einen riesigen Meilenstein bei der Vereinfachung des Migrationspfads zu Intlayer mit Compat Adapter Packages für wichtige i18n-Bibliotheken (react-i18next, next-intl, vue-i18n, etc.) und fügt Unterstützung für reichhaltige Inhaltsstrukturen hinzu: Collections und Variants.

Inhaltsverzeichnis

Compat Adapter Packages

Die Migration von beliebten i18n-Bibliotheken zu Intlayer ist jetzt einfacher denn je. Wir haben fünf Kompatibilitätspakete erstellt, die die exakt gleichen öffentlichen APIs wie Standard-i18n-Bibliotheken bereitstellen, aber die gesamte Übersetzungsarbeit zur Laufzeit an Intlayer delegieren.

Gleiche öffentliche API mit strenger Typisierung

Durch das Ersetzen von Imports erhalten Sie alle Vorteile von Intlayer (einschließlich Compile-Time-Typsicherheit gegenüber Ihren tatsächlichen Dictionaries) mit minimalen Codeänderungen:

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/react-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n
• @intlayer/lingui

Ändern Sie zum Beispiel einfach:

import { useTranslation } from "react-i18next";

zu:

import { useTranslation } from "@intlayer/react-i18next";

Ihre Keys werden nun streng typisiert gegenüber Ihren Intlayer-Dictionaries, was eine vollständige Dot-Path-Auto-Vervollständigung in Ihrer IDE bietet!

Bundler Alias Plugins (Vite, Next.js, Turbopack)

Um die Migration ohne manuelles Umschreiben aller Import-Statements zu ermöglichen, enthält jedes Compat Adapter Package ein benutzerdefiniertes Bundler-Plugin (Vite oder Next.js) unter dem Subpfad /plugin.

Diese Plugins schreiben bestehende Imports (z.B. react-i18next oder next-intl) zur Build-Zeit automatisch in ihre @intlayer/*-Äquivalente um.

Next.js (Webpack / Turbopack) Beispiel

Anstelle von withIntlayer umschließen Sie Ihre Next.js-Konfiguration mit dem Kompatibilitäts-Plugin:

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
import type { NextConfig } from "next";

const withIntlayer = createNextI18nPlugin();
const nextConfig: NextConfig = {};

export default withIntlayer(nextConfig);

Vite (React, Vue, Solid, Svelte) Beispiel

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";

export default defineConfig({
  plugins: [vueI18nVitePlugin()],
});

Mutualized Runtime Resolver

Alle Kompatibilitätsadapter leiten die Übersetzungsauflösung nun über einen einzigen, hochoptimierten Runtime-Parser: @intlayer/core/messageFormat.

• Interpolate Message: Löst Standard {{var}} (Leerzeichen & Dot-Pfade), ICU-formatierte Argumente ({v, number, percent} etc.) und einfache {var}-Templates auf.
• Message Node Resolver: Löst verschachtelte Nodes auf: insert(), plural() (CLDR-Pluralregeln), enu() (Aufzählung), gender(), HTML-Tags, Arrays und aufrufbare Funktions-Nodes.
• Tokenized Tag Parser: Unterstützt Inline-XML/HTML-Tags und nummerierte Tags (z.B. <1>children</1>), um Rich-Text-Rendering out-of-the-box zu ermöglichen.

Feature Spec: Collections & Variants

Intlayer v9 geht über statische Schlüssel-Wert-Objekte hinaus und ermöglicht es Dictionaries, dynamische Layout-Strukturen zu deklarieren, die End-to-End vollständig typisiert sind.

1. Collections

Definieren Sie eine CMS-verwaltete Liste geordneter Elemente (z.B. FAQs, Produkte oder Bloglisten):

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

export default {
  key: "faq",
  item: 1,
  content: {
    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
  },
} satisfies Dictionary;

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

export default {
  key: "faq",
  item: 2,
  content: {
    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
  },
} satisfies Dictionary;

Verwendung:

// Fetch all items as an array
const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]

// Fetch a single item by index
const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

2. Variants

Liefern Sie A/B-Tests, saisonale Header, Feature Flags oder benutzerdefinierte Landing Pages:

String-Varianten (z. B. A/B-Tests)

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

export default {
  key: "hero-banner",
  variant: "default",
  content: {
    control: t({ de: "Willkommen", en: "Welcome", fr: "Bienvenue" }),
    black_friday: t({
      de: "Jetzt einkaufen",
      en: "Shop now",
      fr: "Acheter maintenant",
    }),
  },
} satisfies Dictionary;

Verwendung:

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

Objekt-Varianten (z. B. Dynamic Records)

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

export default {
  key: "product-copy",
  variant: {
    id: "prod_123",
    category: "books",
  },
  content: {
    title: t({ de: "Clean Code", en: "Clean Code", fr: "Code Propre" }),
  },
} satisfies Dictionary;

Verwendung:

// Ruft nur das angeforderte Element dynamisch ab (erfordert Suspense)
const product = useIntlayer("product-copy", {
  variant: { id: "prod_123", category: "books" },
});

@intlayer/analytics: Content-Exposure-Tracking & A/B-Tests

Ein neues optionales Paket, @intlayer/analytics, zeigt Ihnen, welche Inhalte Ihren Besuchern tatsächlich angezeigt werden, und schließt damit den Kreis zu Collections & Variants, indem es Ihnen ermöglicht, Inhalte per A/B-Test zu testen und Conversions pro Variante zu messen.

• Tracking auf Provider-Ebene: IntlayerProvider (React / Next.js / React Native) erfasst automatisch page_view-Ereignisse beim Laden, bei Routenwechseln und bei Sprachwechseln.
• Tracking auf Knotenebene: Jede Auflösung von useIntlayer meldet ein content_exposure-Ereignis, welcher Dictionary-Schlüssel, Key-Path, welche Sprache und (falls zutreffend) welche A/B-Variante angezeigt wurde. Wiederholte Anzeigen desselben Knotens innerhalb eines Flush-Fensters werden zu einem Ereignis zusammengefasst.
• Deterministische A/B-Zuweisung: getVariant(experimentKey, variants) weist jeder Sitzung eine Variante zu, ohne Server-Roundtrip, sodass kein Flackern vor dem ersten Rendering auftritt.
• useConversion(): ordnet ein Ziel (Registrierung, Klick, Kauf …) der Variante zu, der die Sitzung ausgesetzt war.
• Keine Kosten, wenn nicht installiert: gleiches tree-shakeable Muster wie bei @intlayer/editor, dynamischer, in try/catch gekapselter import(), plus eine Build-Zeit-Umgebungsvariable (INTLAYER_ANALYTICS_ENABLED), die die gesamte Integration für Apps, die sie nicht nutzen, per Dead-Code-Elimination entfernt.
• Kein neues Konfigurationsschema: verwendet weiterhin editor.backendURL (Ingestion-Endpunkt / Self-Hosting) und editor.clientId (Projektschlüssel, zugleich Aktivierungsschalter).
• Datenschutzfreundlich: anonymes Session-Hashing (SHA-256, keine Rohkennungen gespeichert), keine IP-Speicherung, nur grobe länderbasierte Geolokalisierung, gebündelte Anfragen etwa alle 20 Sekunden.
• Dashboard: Eine neue Analytics-Seite (in der Seitenleiste sichtbar, sobald ein Projekt ausgewählt ist) zeigt aktive Nutzer, Nutzer heute, Nutzer der letzten 7/30/90 Tage, einen Besucherentwicklungsgraphen sowie Aufschlüsselungen nach Sprache und Standort.

npm install @intlayer/analytics

Bereits heute verfügbar für React, Next.js und React Native (über react-intlayer); weitere Framework-Anbindungen (Vue, Svelte, Angular, …) sind geplant und folgen demselben Rollout-Muster wie @intlayer/editor. Die vollständige Anleitung finden Sie in der Analytics-Dokumentation.

Vite Plugin: Bundled Compiler & Proxy

Das intlayer() Vite Plugin bündelt nun den Compiler und den Locale-Routing Proxy direkt, sodass die meisten Projekte nur ein einzelnes Plugin in vite.config.ts benötigen:

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer()],
});

• Compiler: Aktiviert sich automatisch, wenn compiler.enabled auf true gesetzt ist und ein compiler.output Pfad konfiguriert ist. Sie müssen intlayerCompiler() nicht mehr separat registrieren.
• Proxy: Aktiviert sich automatisch basierend auf der neuen routing.enableProxy Option (true standardmäßig). Es verbindet die Locale-Erkennung / Umleitung / Rewrite Middleware in Entwicklung, Preview und Production SSR. Sie müssen intlayerProxy() nicht mehr separat registrieren.

routing.enableProxy Option

Eine neue routing.enableProxy Option kontrolliert, ob der Locale-Routing-Proxy eingebunden ist. Sie ist standardmäßig auf true gesetzt. Deaktivieren Sie sie, wenn Sie das Locale-Routing selbst handhaben möchten:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  routing: {
    enableProxy: false, // Standard: true
  },
};

export default config;

Die eigenständigen intlayerCompiler() und intlayerProxy() Plugins bleiben für erweiterte Setups exportiert. Die Registrierung neben intlayer() ist sicher, jedes Plugin dedupliziert sich selbst und läuft nur einmal.

Compiler standardmäßig deaktiviert

Ab Intlayer v9 ist der Compiler standardmäßig deaktiviert (compiler.enabled ist jetzt standardmäßig false). Um die Extraktion Ihrer .content.ts-Dateien zur Build-Zeit zu aktivieren, setzen Sie compiler.enabled: true in Ihrer Konfiguration:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    enabled: true, // Standard: false, seit v9 erforderlich, um den Compiler zu aktivieren
    output: ({ fileName }) => `./${fileName}.content.ts`,
  },
};

export default config;

Wenn der Compiler deaktiviert ist, überspringt Intlayer den Extraktionsschritt zur Build-Zeit und verlässt sich auf Ihre bereits deklarierten Dictionaries. Aktivieren Sie ihn nur, wenn das Bundler-Plugin (@intlayer/swc, @intlayer/babel oder das intlayer() Vite-Plugin) den Inhalt automatisch extrahieren soll.

React Native: Importe aus einem einzigen Paket

In einer React Native- oder Expo-App müssen Sie nicht mehr beide Pakete react-intlayer und react-native-intlayer jonglieren. Das Paket react-native-intlayer re-exportiert nun die vollständige react-intlayer API (Hooks, Utilities sowie die Subpfade /format, /html und /markdown), und sein IntlayerProvider wendet automatisch die React Native Polyfills an.

Importieren Sie alles aus dem einzigen Paket react-native-intlayer:

import {
  IntlayerProvider,
  useIntlayer,
  useLocale,
} from "react-native-intlayer";

npm install intlayer react-native-intlayer

Importe aus react-intlayer funktionieren weiterhin, aber react-native-intlayer ist nun der empfohlene einzige Einstiegspunkt für React Native, sein Provider liefert die Polyfills, die der weborientierte react-intlayer-Provider nicht enthält.

CMS SDK: Intlayer als Headless-Content-Datenbank nutzen

Intlayer v9 enthält ein sauberes, sich selbst authentifizierendes SDK in @intlayer/api, um programmgesteuert mit dem CMS zu interagieren – Projekte abrufen, Dictionaries abrufen sowie diese von Ihrem eigenen Server, Skripten oder CI aus pushen oder aktualisieren. Die Authentifizierung (OAuth2 client_credentials) wird für Sie übernommen und erneuert.

Das SDK ist in zwei getrennte Importe aufgeteilt, sodass Ihr Bundle nur die Domänen enthält, die Sie tatsächlich verwenden:

1. createIntlayerCMS – ein leichtgewichtiger Authentifikator, der die Anmeldedaten und das verwaltete Token hält (kein Domänen-Client gebündelt).
2. dictionaryEndpoint, projectEndpoint, … – Endpoint-Binder pro Domäne, jeweils aus ihrem eigenen Unterpfad importiert.

import { createIntlayerCMS } from "@intlayer/api";
import { dictionaryEndpoint } from "@intlayer/api/dictionary";

// Konfiguration ist optional: Anmeldedaten fallen auf INTLAYER_CLIENT_ID /
// INTLAYER_CLIENT_SECRET zurück, aufgelöst durch `@intlayer/config/built`.
const cms = createIntlayerCMS();

// Lesen
const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();

// Schreiben – nutze das CMS wie eine Datenbank
await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Sicherheit: Die CMS-Anmeldedaten gewähren Schreibzugriff auf Ihre Inhalte. Erstellen Sie den Authentifikator immer nur serverseitig – senden Sie clientId / clientSecret niemals an den Browser.

Self-Hosting

Intlayer v9 bietet erstklassige Unterstützung für den Betrieb Ihrer eigenen Intlayer-Instanz mit einem einzigen Befehl – kein Intlayer Cloud-Konto erforderlich.

curl -fsSL https://intlayer.org/install.sh | sh

Das Installationsprogramm lädt eine docker-compose.yml und eine .env herunter, generiert automatisch die erforderlichen Secrets und führt docker compose up -d aus. Alles – das Dashboard, die API, die Datenbank, der Objektspeicher und die transaktionale E-Mail – läuft lokal in Containern.

Migrationshinweise von v8

Wenn Sie von v8 upgraden, beachten Sie, dass v9 keine Breaking Changes enthält. Hier sind jedoch die wichtigsten Änderungen:

• Compiler standardmäßig deaktiviert: compiler.enabled ist jetzt standardmäßig false. Wenn Sie auf die Extraktion Ihrer .content.ts-Dateien zur Build-Zeit angewiesen sind, setzen Sie compiler.enabled: true in Ihrer intlayer.config.ts.
• Vite-Plugin: Der Compiler und der Locale-Routing-Proxy sind nun in intlayer() gebündelt. Falls Sie zuvor intlayerCompiler() oder intlayerProxy() manuell registriert haben, können Sie diese entfernen – sie werden automatisch dedupliziert, sodass das Beibehalten harmlos ist. Verwenden Sie routing.enableProxy: false, um den Proxy zu deaktivieren.
• Locales & Dialects: Wenn Sie externe i18n-Abhängigkeiten verwenden, fügen Sie deren entsprechende Kompatibilitätsadapter-Plugins in Ihrer Konfiguration oder Ihrem Bundler-Setup hinzu, um Imports automatisch umzuschreiben.
• Custom Selectors: Beim Aufruf von useIntlayer ist der zweite Parameter nun für ein Options-Objekt reserviert, das { locale, item, variant } enthält. Wenn Sie zuvor direkt einen Locale-String übergeben haben, können Sie dies weiterhin tun, aber die Verwendung des Options-Objekts wird für erweiterte Auswahlen empfohlen.
• React Native: react-native-intlayer re-exportiert nun die gesamte react-intlayer API. Importieren Sie in einer React Native App alles aus react-native-intlayer und entfernen Sie die direkte react-intlayer-Abhängigkeit. Bestehende react-intlayer-Imports funktionieren weiterhin.

Nützliche Links