@intlayer/docs 7.0.0-canary.1 → 7.0.0-canary.3

package/docs/de/releases/v7.md

@@ -0,0 +1,503 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Neue Intlayer v7 - Was ist neu?
+description: Entdecken Sie, was neu ist in Intlayer v7. Wichtige Verbesserungen in Leistung, Entwicklererfahrung und neue Funktionen zur Optimierung Ihres Internationalisierungs-Workflows.
+keywords:
+  - Intlayer
+  - Lokalisierung
+  - Entwicklung
+  - Leistung
+  - Entwicklererfahrung
+  - Funktionen
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# 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.
+
+## 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 Paketgröß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.
+
+```bash
+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:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Verhalten in v7:**
+
+```tsx
+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:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum, das alle Sprachen enthält -> nicht tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// String-Typ -> vollständig tree-shakeable
+
+const 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](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) 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
+
+```typescript
+// intlayer.config.ts
+export 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:
+
+```typescript
+// Speicher deaktivieren
+storage: false
+
+// Einfache Speichertypen
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie mit benutzerdefinierten Attributen
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage mit benutzerdefiniertem Schlüssel
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Mehrere Speichertypen zur Redundanz
+storage: ['cookie', 'localStorage']
+```
+
+### DSGVO-konformes Konfigurationsbeispiel
+
+Für produktive Anwendungen, die Funktionalität mit DSGVO-Konformität in Einklang bringen müssen:
+
+```typescript
+// intlayer.config.ts
+export 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:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Kann lokal für jeden Hook überschrieben werden:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Hinweis:** Cookies sind standardmäßig aktiviert.
+**Hinweis:** Prüfen Sie die [DSGVO-Cookie-Anforderungen](https://gdpr.eu/cookies/) 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.
+
+---
+
+## 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
+
+```typescript
+// Überschreibt die aktuelle Datei mit allen Sprachversionen
+const content = {
+  key: "example",
+  fill: true, // Überschreibt diese Datei
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Füllt eine separate Datei, ohne die aktuelle Datei zu ändern
+const content = {
+  key: "example",
+  fill: "./translations.json", // Erstellt/aktualisiert translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Deaktiviert Auto-Fill
+const content = {
+  key: "example",
+  fill: false, // Kein Auto-Fill
+  content: {
+    title: "Hallo Welt",
+  },
+};
+
+// Komplexe Inhaltsstruktur mit zusammengesetzten Objekten
+const 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
+
+```typescript
+// Große Inhaltsdatei wird automatisch in Chunks aufgeteilt
+const 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`
+
+### Migrationszuordnung
+
+#### Konfigurationszuordnung
+
+| v6 Konfiguration           | v7 Konfiguration                                                     |
+| -------------------------- | -------------------------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                                          |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                                          |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                                 |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                                  |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`                     |
+| `serverSetCookie: 'never'` | `storage: false` oder entfernen Sie den Cookie aus dem Storage-Array |
+
+#### Beispiel Migration
+
+**Vorher (v6):**
+
+````typescript
+export default {
+#### Konfigurationszuordnung
+
+| v6 Konfiguration           | v7 Konfiguration                                     |
+| -------------------------- | ---------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                          |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                          |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                 |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                  |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`     |
+| `serverSetCookie: 'never'` | `storage: false` oder Entfernen des Cookies aus dem Speicher-Array |
+
+#### Beispiel Migration
+
+**Vorher (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+````
+
+**Nachher (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // oder 'cookie', falls Cookie-Speicherung benötigt wird
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Wörterbuch-Inhaltszuordnung
+
+| v6 Wörterbuch-Inhalt | v7 Wörterbuch-Inhalt |
+| -------------------- | -------------------- |
+| `autoFill: xxx`      | `fill: xxx`          |
+
+#### Beispiel Migration
+
+**Vorher (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Überschreibt diese Datei
+  content: {
+    title: "Hallo Welt",
+  },
+};
+```
+
+**Nach (v7):**
+
+```typescript
+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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/releases/v6.md) für weitere Informationen.
+
+---
+
+## Nützliche Links
+
+- [Konfigurationsreferenz](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md)
+- [Middleware-Dokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/packages/next-intlayer/index.md)
+- [TypeScript-Typen](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [DSGVO Cookie-Richtlinien](https://gdpr.eu/cookies/)

package/docs/en/intlayer_with_nextjs_15.md

@@ -1,6 +1,6 @@
 ---
-createdAt: 2024-12-06
-updatedAt: 2025-10-09
+createdAt: 2025-10-25
+updatedAt: 2025-10-25
 title: How to translate your Next.js 15 app – i18n guide 2025
 description: Discover how to make your Next.js 15 website multilingual. Follow the documentation to internationalize (i18n) and translate it.
 keywords:
@@ -18,6 +18,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-next-15-template
 youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
 history:
+  - version: 7.0.0
+    date: 2025-10-25
+    changes: Added mention of `withIntlayerSync()` function
   - version: 6.2.0
     date: 2025-10-09
     changes: Added docs for `useLocale` hook with `onLocaleChange` option

package/docs/en/intlayer_with_nextjs_16.md

@@ -130,7 +130,7 @@ const config = {
 module.exports = config;
 ```
 
-> Through this configuration file, you can set up localized URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
+> Through this configuration file, you can set up localized URLs, proxy redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
 
 ### Step 3: Integrate Intlayer in Your Next.js Configuration
 
@@ -290,7 +290,7 @@ module.exports = LocaleLayout;
 
 > The `[locale]` path segment is used to define the locale. Example: `/en-US/about` will refer to `en-US` and `/fr/about` to `fr`.
 
-> At this stage, you will encounter the error: `Error: Missing <html> and <body> tags in the root layout.`. This is expected because the `/app/page.tsx` file is no longer in use and can be removed. Instead, the `[locale]` path segment will activate the `/app/[locale]/page.tsx` page. Consequently, pages will be accessible via paths like `/en`, `/fr`, `/es` in your browser. To set the default locale as the root page, refer to the `middleware` setup in step 7.
+> At this stage, you will encounter the error: `Error: Missing <html> and <body> tags in the root layout.`. This is expected because the `/app/page.tsx` file is no longer in use and can be removed. Instead, the `[locale]` path segment will activate the `/app/[locale]/page.tsx` page. Consequently, pages will be accessible via paths like `/en`, `/fr`, `/es` in your browser. To set the default locale as the root page, refer to the `proxy` setup in step 7.
 
 Then, implement the `generateStaticParams` function in your application Layout.
 
@@ -637,7 +637,7 @@ const ServerComponentExample = () => {
 
 ### (Optional) Step 7: Configure Proxy for Locale Detection
 
-Set up middleware to detect the user's preferred locale:
+Set up proxy to detect the user's preferred locale:
 
 ```typescript fileName="src/proxy.ts" codeFormat="typescript"
 export { intlayerProxy as proxy } from "next-intlayer/proxy";
@@ -1488,7 +1488,7 @@ export const myServerAction = async () => {
 
 > The `getLocale` function follows a cascading strategy to determine the user's locale:
 >
-> 1. First, it checks the request headers for a locale value that may have been set by the middleware
+> 1. First, it checks the request headers for a locale value that may have been set by the proxy
 > 2. If no locale is found in headers, it looks for a locale stored in cookies
 > 3. If no cookie is found, it attempts to detect the user's preferred language from their browser settings
 > 4. As a last resort, it falls back to the application's configured default locale