Neue Intlayer v7 - Was ist neu?

Willkommen bei Intlayer v7! Dieses große Release bringt bedeutende Verbesserungen in Leistung, Typsicherheit und Entwicklererfahrung. Nachfolgend finden Sie die Highlights, Migrationshinweise und praktische Beispiele.

Inhaltsverzeichnis

Highlights

• Caching-Strategie für schnellere Builds
• Verbesserte TypeScript-Typgenerierung mit sprachspezifischen Typen
• Bundle-Optimierung: Sprachen als Strings statt als Enum
• Neue Routing-Modi: prefix-no-default, prefix-all, no-prefix, search-params
• DSGVO-konforme Sprachspeicherung mit localStorage als Standard
• Flexible Speicher-Konfiguration: Cookies, localStorage, sessionStorage oder mehrere gleichzeitig
• 30 % kleinere Bundle-Größe des Visual Editors
• Erweiterte Middleware-Konfigurationsoptionen
• Aktualisiertes Verhalten des Fill-Kommandos für bessere Inhaltsverwaltung
• Verbesserte Stabilität durch vollständige Aktualisierung der Content-Declaration-Dateien
• Intelligentes Retry-Management für höhere Übersetzungsgenauigkeit
• Parallelisierung für schnellere Übersetzungsverarbeitung
• Intelligentes Chunking zur Handhabung großer Dateien innerhalb der KI-Kontextgrenzen

Leistung: Caching für schnellere Builds

Anstatt bei jedem Build die Content-Declaration-Dateien mit esbuild neu zu erstellen, implementiert Version 7 eine Caching-Strategie, die den Build-Prozess beschleunigt.

npx intlayer build

Das neue Caching-System:

• Speichert kompilierte Content-Declaration-Dateien, um redundante Verarbeitung zu vermeiden
• Erkennt Änderungen und baut nur modifizierte Dateien neu auf
• Reduziert die Build-Zeiten bei großen Projekten erheblich

TypeScript: Sprachspezifische Typgenerierung

TypeScript-Typen werden nun pro Sprache generiert, was eine stärkere Typisierung ermöglicht und Union-Typen über alle Sprachen hinweg eliminiert.

Verhalten in v6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Verhalten in v7:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Vorteile:

• Präzisere Autovervollständigung in Ihrer IDE
• Bessere Typensicherheit ohne Typverschmutzung über verschiedene Sprachen hinweg
• Verbesserte Leistung durch Reduzierung der Typkomplexität

Bundle-Optimierung: Sprachen als Strings

Der Typ Locales ist kein Enum mehr, was bedeutet, dass er jetzt vollständig tree-shakeable ist und Ihr Bundle nicht mehr mit tausenden ungenutzten Sprachdatensätzen aufbläht.

v6:

import { Locales } from "intlayer";// Enum, das alle Sprachen enthält -> nicht tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// String-Typ -> vollständig tree-shakeableconst locale: Locale = Locales.ENGLISH;

Da Locales kein Enum mehr ist, müssen Sie den Typ von Locales zu Locale ändern, um die Sprache als Typ zu erhalten.

Siehe die Implementierungsdetails für weitere Informationen.

Neue Routing-Modi für mehr Flexibilität

v7 führt eine einheitliche routing.mode-Konfiguration ein, die die vorherigen Optionen prefixDefault und noPrefix ersetzt und eine feinere Steuerung der URL-Struktur ermöglicht.

Verfügbare Routing-Modi

• prefix-no-default (Standard): Die Standardsprache hat kein Präfix, andere Sprachen schon
  • /dashboard (en) oder /fr/dashboard (fr)
• prefix-all: Alle Sprachen haben ein Präfix
  • /en/dashboard (en) oder /fr/dashboard (fr)
• no-prefix: Keine Sprachpräfixe in URLs (Sprache wird über Speicher/Header gehandhabt)
  • /dashboard für alle Sprachen
• search-params: Sprache wird als Abfrageparameter übergeben
  • /dashboard?locale=en oder /dashboard?locale=fr

Grundkonfiguration

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // Standard  },};

DSGVO-Konformität: localStorage / Cookie-Speicherung

v7 legt besonderen Wert auf den Schutz der Privatsphäre der Nutzer, indem localStorage als Standard-Speichermechanismus anstelle von Cookies verwendet wird. Diese Änderung unterstützt die DSGVO-Konformität, indem sie die Notwendigkeit einer Cookie-Einwilligung für Spracheinstellungen vermeidet.

Speicher-Konfigurationsoptionen

Das neue Feld routing.storage ist zusätzlich zu den bisherigen Optionen middleware.cookieName und middleware.serverSetCookie verfügbar und bietet flexible Speicher-Konfigurationen:

// Speicher deaktivierenstorage: false// Einfache Speichertypenstorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie mit benutzerdefinierten Attributenstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage mit benutzerdefiniertem Schlüsselstorage: {  type: 'localStorage',  name: 'custom-locale'}// Mehrere Speichertypen zur Redundanzstorage: ['cookie', 'localStorage']

DSGVO-konformes Konfigurationsbeispiel

Für produktive Anwendungen, die Funktionalität mit DSGVO-Konformität in Einklang bringen müssen:

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Primärer Speicher (kein Einverständnis erforderlich)        name: "user-locale",      },      {        type: "cookie", // Optionale Cookie-Speicherung (erfordert Einverständnis)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Aktivieren / Deaktivieren der Cookie-Speicherung

Beispiel mit React / Next.js:

Kann global definiert werden:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Kann lokal für jeden Hook überschrieben werden:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Hinweis: Cookies sind standardmäßig aktiviert. Hinweis: Prüfen Sie die DSGVO-Cookie-Anforderungen für Ihren spezifischen Anwendungsfall.

Visual Editor: 30 % kleineres Paket

Das Visual Editor-Paket wurde optimiert und ist nun 30 % kleiner als die vorherige Version, dank:

• Verbesserungen der Leistung des Code-Editors
• Entfernung unnötiger Abhängigkeiten von Intlayer-Kernpaketen
• Besseres Tree-Shaking und Modul-Bündelung

Dies führt zu schnelleren Downloadzeiten und verbesserter Laufzeitleistung Ihrer Anwendung.

Automatische Code-Formatierung: formatCommand-Konfiguration

v7 führt die formatCommand-Option in der Editor-Konfiguration ein, die es Ihnen ermöglicht, Inhaltsdateien automatisch zu formatieren, wenn sie von Intlayer geschrieben werden. Dies gewährleistet einen konsistenten Code-Stil und eine konsistente Formatierung in Ihren Content-Deklarationsdateien.

Falls nicht gesetzt, versucht Intlayer, den Format-Befehl automatisch zu erkennen. Durch den Versuch, die folgenden Befehle aufzulösen: prettier, biome, eslint.

Konfiguration

Die formatCommand-Option akzeptiert eine String-Vorlage, wobei {{file}} durch den tatsächlichen Dateipfad ersetzt wird:

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

Unterstützte Formatter

Sie können jeden Code-Formatter verwenden, der Dateipfade als Argumente akzeptiert:

Using Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Using Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Using ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Using Bun's built-in formatter:

formatCommand: 'bun format "{{file}}"';

Vorteile

• Konsistente Formatierung: Alle Inhaltsdateien werden automatisch gemäß den Stilrichtlinien Ihres Projekts formatiert
• Developer Experience: Keine manuelle Formatierung von Dateien nach dem Schreiben durch Intlayer erforderlich
• Team-Konsistenz: Stellt sicher, dass alle Teammitglieder die gleiche Formatierung auf Inhaltsdateien anwenden
• CI/CD-Integration: Inhaltsdateien behalten konsistente Formatierung in automatisierten Workflows bei

Funktionsweise

Wenn Intlayer eine Content-Deklarationsdatei (.content.ts, .content.js, etc.) schreibt oder aktualisiert, führt es automatisch den angegebenen Format-Befehl auf der Datei aus. Der Platzhalter {{file}} wird durch den tatsächlichen Dateipfad ersetzt, und der Befehl wird im Basisverzeichnis des Projekts ausgeführt.

Dictionary-Konfiguration: Bessere Organisation und Struktur

v7 führt einen neuen dedizierten dictionary-Konfigurationsbereich ein, der eine bessere Organisation für wörterbuchbezogene Einstellungen und verbessertes Content-Management bietet.

Neue Dictionary-Konfigurationsstruktur

Die fill-Eigenschaft wurde aus dem content-Abschnitt in einen neuen dictionary-Abschnitt verschoben, was eine klarere Trennung der Verantwortlichkeiten ermöglicht:

v6-Konfiguration:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

v7-Konfiguration:

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

Vorteile der neuen Struktur

• Klarere Organisation: Dictionary-spezifische Einstellungen sind nun zusammengefasst
• Bessere Separation of Concerns: Content Discovery vs. Dictionary-Operationen sind klar getrennt
• Verbesserte Wartbarkeit: Einfacher zu verstehen und zu modifizieren Dictionary-bezogene Konfigurationen
• Zukünftige Erweiterbarkeit: Der Dictionary-Bereich kann zusätzliche Dictionary-spezifische Einstellungen aufnehmen
• Umfassendes Dictionary-Management: Umfasst Eigenschaften wie title, live, priority, tags, version und description zum Erstellen und Verwalten neuer Dictionaries

Konfigurationsverwendung

Die Wörterbuchkonfiguration dient zwei Hauptzwecken:

1. Standardwerte: Definieren Sie Standardwerte beim Erstellen von Content-Deklarationsdateien
2. Fallback-Verhalten: Stellen Sie Fallback-Werte bereit, wenn bestimmte Felder nicht definiert sind, sodass Sie das Wörterbuch-Betriebsverhalten global definieren können

Der Wörterbuchbereich umfasst umfassende Eigenschaften zur Wörterbuchverwaltung:

• fill: Auto-Fill-Verhalten für die Content-Generierung
• title: Standardtitel für neue Wörterbücher
• live: Live-Sync-Konfiguration für Echtzeit-Updates
• priority: Prioritätseinstellungen für die Wörterbuchauflösung
• tags: Standard-Tags für die Content-Organisation
• version: Versionsverwaltung für Wörterbuch-Updates
• description: Standardbeschreibung für neue Inhalte

Weitere Informationen zu Content-Deklarationsdateien und wie Konfigurationswerte angewendet werden, finden Sie in der Content-Datei-Dokumentation.

Fill-Befehl: Aktualisiertes Verhalten für besseres Content-Management

v7 führt ein verbessertes Verhalten für den fill-Befehl ein, das ein vorhersehbareres und flexibleres Content-Management ermöglicht:

Neues Fill-Verhalten

• fill: true - Überschreibt die aktuelle Datei mit ausgefülltem Inhalt für alle Sprachen
• fill: "path/to/file" - Füllt die angegebene Datei, ohne die aktuelle Datei zu verändern
• fill: false - Deaktiviert das automatische Ausfüllen vollständig

Verbesserte Unterstützung für komplexe Inhaltsstrukturen

Der Fill-Befehl unterstützt jetzt komplexe Inhaltsdeklarationsstrukturen, einschließlich:

• Zusammengesetzte Objekte: Inhaltsdeklarationen, die auf andere Objekte verweisen
• Destrukturierter Inhalt: Inhalt, der Destrukturierungsmuster verwendet
• Verschachtelte Verweise: Objekte, die sich in komplexen Hierarchien gegenseitig aufrufen
• Dynamische Inhaltsstrukturen: Inhalt mit bedingten oder berechneten Eigenschaften

Vorteile

• Klarere Absicht: Das Verhalten ist jetzt expliziter bezüglich dessen, was geändert wird
• Bessere Trennung: Inhaltsdateien können von ausgefüllten Übersetzungen getrennt gehalten werden
• Verbesserter Arbeitsablauf: Entwickler haben mehr Kontrolle darüber, wo Übersetzungen gespeichert werden
• Unterstützung komplexer Strukturen: Umgang mit anspruchsvollen Inhaltsarchitekturen mit mehreren miteinander verbundenen Objekten

Beispielanwendung

// Überschreibt die aktuelle Datei mit allen Sprachversionenconst content = {  key: "example",  fill: true, // Überschreibt diese Datei  content: {    title: "Hello World",  },};// Füllt eine separate Datei, ohne die aktuelle Datei zu ändernconst content = {  key: "example",  fill: "./translations.json", // Erstellt/aktualisiert translations.json  content: {    title: "Hello World",  },};// Deaktiviert Auto-Fillconst content = {  key: "example",  fill: false, // Kein Auto-Fill  content: {    title: "Hallo Welt",  },};// Komplexe Inhaltsstruktur mit zusammengesetzten Objektenconst sharedContent = {  buttons: {    save: "Speichern", // Speichern-Button    cancel: "Abbrechen", // Abbrechen-Button  },};const content = {  key: "complex-example",  fill: true,  content: {    // Verweise auf andere Objekte    sharedContent,    // Destrukturierter Inhalt    ...sharedContent,    // Verschachtelte Verweise    sections: [      {        ...sharedContent.buttons,        header: "Abschnitt 1",      },    ],  },};

Verbesserte Stabilität und Übersetzungsverwaltung

v7 führt mehrere Verbesserungen ein, um die Inhaltsübersetzung zuverlässiger und effizienter zu gestalten:

Vollständige Aktualisierung der Inhaltsdeklarationsdateien

Das System aktualisiert jetzt .content.{ts,js,cjs,mjs}-Dateien anstelle von Teilaktualisierungen, was sicherstellt:

• Datenintegrität: Vollständige Datei-Neuschreibungen verhindern partielle Updates, die Inhalte beschädigen könnten
• Konsistenz: Alle Sprachversionen werden atomar aktualisiert, um Synchronisation zu gewährleisten
• Zuverlässigkeit: Verringert das Risiko unvollständiger oder fehlerhafter Inhaltsdateien

Intelligentes Wiederholungsmanagement

Neue Wiederholungsmechanismen verhindern das Hochladen von Inhalten in falschen Formaten und vermeiden, dass der gesamte Füllprozess bei einem fehlgeschlagenen Request abbricht.

Parallelisierung für schnellere Verarbeitung

Übersetzungsoperationen werden jetzt in einer Warteschlange ausgeführt, um sie parallel laufen zu lassen. Dies beschleunigt den Prozess erheblich.

Intelligentes Chunking für große Dateien

Fortschrittliche Chunking-Strategien verarbeiten große Inhaltsdateien, ohne die Kontextfenster der KI zu überschreiten:

Beispiel-Workflow

// Große Inhaltsdatei wird automatisch in Chunks aufgeteiltconst content = {  key: "large-documentation",  fill: true,  content: {    // Große Inhalte werden automatisch für die KI-Verarbeitung in Abschnitte unterteilt    introduction: "..." // 5000+ Zeichen    sections: [      // Mehrere große Abschnitte    ]  }};

Das System führt automatisch aus:

1. Analysiert die Größe und Struktur des Inhalts
2. Unterteilt den Inhalt angemessen in Abschnitte
3. Verarbeitet die Abschnitte parallel
4. Validiert und versucht bei Bedarf erneut
5. Rekonstruiert die vollständige Datei

Migrationshinweise von v6

Entfernte Konfigurationen

• middleware.cookieName: Ersetzt durch routing.storage
• middleware.serverSetCookie: Ersetzt durch routing.storage
• middleware.prefixDefault: Ersetzt durch routing.mode
• middleware.noPrefix: Ersetzt durch routing.mode

Neue Konfigurationen

• editor.formatCommand: Neue Option für automatische Code-Formatierung von Content-Dateien

Migrationszuordnung

Konfigurationszuordnung

Beispiel Migration

Vorher (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Nachher (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // oder 'cookie', falls Cookie-Speicherung benötigt wird    headerName: "x-intlayer-locale",    basePath: "",  },};

Wörterbuch-Inhaltszuordnung

Beispiel Migration

Vorher (v6):

const content = {  key: "example",  autoFill: true, // Überschreibt diese Datei  content: {    title: "Hallo Welt",  },};

Nach (v7):

const content = {  key: "example",  fill: true, // Überschreibt diese Datei  content: {    title: "Hallo Welt",  },};

Migrationshinweise von v5 zu v6

Siehe die Migrationshinweise von v5 zu v6 für weitere Informationen.

Nützliche Links

• Konfigurationsreferenz
• Middleware-Dokumentation
• TypeScript-Typen
• DSGVO Cookie-Richtlinien