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 arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst 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" },});

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();// Lesenconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Schreiben – nutze das CMS wie eine Datenbankawait 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.

Enthaltene Dienste

Chromium (für die Puppeteer-Screenshot-Generierung verwendet) ist im Backend-Image gebündelt – kein zusätzlicher Container erforderlich.

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

• Leitfaden für Compat Adapter Packages
• Dynamische Dictionaries – Collections & Variants
• Konfigurationsreferenz
• CMS SDK – Programmatischer Zugriff mit @intlayer/api
• Self-Hosting-Leitfaden