@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.3

package/docs/de/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Sync JSON Plugin
 description: Synchronisieren Sie Intlayer-Wörterbücher mit Drittanbieter-i18n-JSON-Dateien (i18next, next-intl, react-intl, vue-i18n und mehr). Behalten Sie Ihr bestehendes i18n bei und verwenden Sie Intlayer, um Ihre Nachrichten zu verwalten, zu übersetzen und zu testen.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Option `splitKeys` hinzugefügt (ein Wörterbuch pro Top-Level-Namespace-Schlüssel) für next-intl / react-intl Single-File-Layouts"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Unterstützung für ICU- und i18next-Formate hinzugefügt"
@@ -62,7 +65,63 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Schnellstart
+## Plugins
+
+Dieses Paket bietet zwei Plugins:
+
+- `loadJSON`: Lädt JSON-Dateien in Intlayer-Wörterbücher.
+  - Dieses Plugin wird verwendet, um JSON-Dateien aus einer Quelle zu laden, und diese werden in Intlayer-Wörterbücher geladen. Es kann die gesamte Codebasis durchsuchen und nach bestimmten JSON-Dateien suchen.
+    Dieses Plugin kann verwendet werden
+    - wenn Sie eine i18n-Bibliothek verwenden, die einen bestimmten Speicherort für Ihre zu ladenden JSON-Dateien vorschreibt (z.B. `next-intl`, `i18next`, `react-intl`, `vue-i18n` usw.), Sie aber Ihre Inhaltsdeklaration an einer beliebigen Stelle in Ihrer Codebasis platzieren möchten.
+    - Es kann auch verwendet werden, wenn Sie Ihre Nachrichten von einer Remote-Quelle (z.B. einem CMS, einer API usw.) abrufen und Ihre Nachrichten in JSON-Dateien speichern möchten.
+
+  > Im Hintergrund scannt dieses Plugin die gesamte Codebasis, sucht nach bestimmten JSON-Dateien und lädt sie in Intlayer-Wörterbücher.
+  > Beachten Sie, dass dieses Plugin die Ausgabe und Übersetzungen nicht zurück in die JSON-Dateien schreibt.
+
+- `syncJSON`: Synchronisiert JSON-Dateien mit Intlayer-Wörterbüchern.
+  - Dieses Plugin wird verwendet, um JSON-Dateien mit Intlayer-Wörterbüchern zu synchronisieren. Es kann den angegebenen Speicherort scannen und die JSON-Dateien laden, die dem Muster für bestimmte JSON-Dateien entsprechen. Dieses Plugin ist nützlich, wenn Sie die Vorteile von Intlayer nutzen möchten, während Sie eine andere i18n-Bibliothek verwenden.
+
+## Beide Plugins verwenden
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Halten Sie Ihre aktuellen JSON-Dateien mit den Intlayer-Wörterbüchern synchron
+  plugins: [
+    /**
+     * Lädt alle JSON-Dateien im src-Verzeichnis, die dem Muster {key}.i18n.json entsprechen
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Stellt sicher, dass diese JSON-Dateien Vorrang vor Dateien unter `./locales/en/${key}.json` haben
+      format: "intlayer", // Format des JSON-Inhalts
+    }),
+    /**
+     * Lädt die Ausgabe und Übersetzungen und schreibt sie zurück in die JSON-Dateien im locales-Verzeichnis
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Schnellstart
 
 Fügen Sie das Plugin zu Ihrer `intlayer.config.ts` hinzu und verweisen Sie auf Ihre bestehende JSON-Struktur.
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Pro-Locale, pro-Namespace Layout (z.B. next-intl, i18next mit Namespaces)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,27 @@ export default config;
 Alternative: Einzelne Datei pro Locale (häufig bei i18next/react-intl Setups):
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### Funktionsweise
+#### Funktionsweise
 
 - Lesen: Das Plugin entdeckt JSON-Dateien über Ihren `source`-Builder und lädt sie als Intlayer-Wörterbücher.
 - Schreiben: Nach dem Build und Ausfüllen schreibt es die lokalisierten JSON-Dateien zurück an dieselben Pfade (mit einer abschließenden neuen Zeile, um Formatierungsprobleme zu vermeiden).
@@ -112,6 +185,7 @@ syncJSON({
   location?: string, // optionales Label, Standard: "plugin"
   priority?: number, // optionale Priorität zur Konfliktlösung, Standard: 0
   format?: 'intlayer' | 'icu' | 'i18next', // optionaler Formatierer, verwendet für Intlayer-Runtime-Kompatibilität
+  splitKeys?: boolean, // optional, teilt eine einzelne Datei in ein Wörterbuch pro Top-Level-Schlüssel (automatisch erkannt)
 });
 ```
 
@@ -136,17 +210,49 @@ syncJSON({
 }),
 ```
 
-## Mehrere JSON-Quellen und Priorität
+#### `splitKeys` (boolean)
+
+Steuert, ob eine einzelne JSON-Datei, deren **Top-Level-Schlüssel Namespaces sind**, zu einem Wörterbuch pro Top-Level-Schlüssel werden soll, anstatt eines einzelnen Wörterbuchs, das die gesamte Datei enthält.
+
+Dies entspricht dem Namespace-Modell von Bibliotheken wie `next-intl` und `react-intl`, bei denen eine `messages/{locale}.json`-Datei mehrere Namespaces durch ihre Top-Level-Schlüssel gruppiert, wobei jeder unabhängig angesprochen wird (z.B. `useTranslations('Hero')` löst sich in das `Hero`-Wörterbuch auf).
+
+- `undefined` (Standard): **automatisch erkannt** — die Datei wird aufgeteilt, wenn das `source`-Muster kein `{key}`-Segment enthält (eine Datei enthält jeden Namespace), und andernfalls als einzelnes Wörterbuch beibehalten (eine Datei pro Schlüssel).
+- `true`: teilt jeden Top-Level-Schlüssel immer in ein eigenes Wörterbuch auf.
+- `false`: niemals aufteilen; die gesamte Datei wird zu einem einzigen Wörterbuch.
+
+Angenommen, eine einzelne `messages/{locale}.json`-Datei:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // impliziert, da das Muster kein `{key}`-Segment enthält
+}),
+```
+
+Dies erzeugt drei Wörterbücher — `Hero`, `Nav` und `About` — sodass `useTranslations('Hero')` (next-intl) korrekt aufgelöst wird. Beim Zurückschreiben werden alle Namespaces wieder in derselben pro-Locale-Datei zusammengeführt.
+
+> Wenn Sie das explizite `{key}`-Segment in Ihrer `source` beibehalten (z.B. `./locales/${locale}/${key}.json`), ist jede Datei bereits ein Namespace, sodass die Aufteilung standardmäßig deaktiviert ist.
+
+### Mehrere JSON-Quellen und Priorität
 
 Sie können mehrere `syncJSON`-Plugins hinzufügen, um verschiedene JSON-Quellen zu synchronisieren. Dies ist nützlich, wenn Sie mehrere i18n-Bibliotheken oder unterschiedliche JSON-Strukturen in Ihrem Projekt haben.
 
-### Prioritätssystem
+#### Prioritätssystem
 
 Wenn mehrere Plugins denselben Wörterbuchschlüssel ansprechen, bestimmt der Parameter `priority`, welches Plugin Vorrang hat:
 
 - Höhere Prioritätszahlen haben Vorrang vor niedrigeren
 - Die Standardpriorität von `.content`-Dateien ist `0`
-- Die Standardpriorität von Plugin-Content-Dateien ist `-1`
+- Die Standardpriorität von Plugins ist `0`
 - Plugins mit derselben Priorität werden in der Reihenfolge verarbeitet, in der sie in der Konfiguration erscheinen
 
 ```ts fileName="intlayer.config.ts"
@@ -189,73 +295,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Konfliktlösung
+## Load JSON Plugin
 
-Wenn derselbe Übersetzungsschlüssel in mehreren JSON-Quellen vorhanden ist:
+### Schnellstart
 
-1. Bestimmt das Plugin mit der höchsten Priorität den endgültigen Wert
-2. Werden Quellen mit niedrigerer Priorität als Fallbacks für fehlende Schlüssel verwendet
-3. Ermöglicht es Ihnen, Legacy-Übersetzungen beizubehalten und gleichzeitig schrittweise auf neue Strukturen umzusteigen
+Fügen Sie das Plugin zu Ihrer `intlayer.config.ts` hinzu, um vorhandene JSON-Dateien als Intlayer-Wörterbücher zu importieren. Dieses Plugin ist schreibgeschützt (keine Schreibvorgänge auf die Festplatte):
 
-## Integrationen
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-Nachfolgend sind gängige Zuordnungen aufgeführt. Belassen Sie Ihre Laufzeit unverändert; fügen Sie nur das Plugin hinzu.
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-### i18next
+  plugins: [
+    // Importiert JSON-Nachrichten, die sich überall in Ihrem Quellbaum befinden
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Lädt eine einzelne Locale pro Plugin-Instanz (standardmäßig die Standard-Locale der Konfiguration)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-Typische Dateistruktur: `./public/locales/{locale}/{namespace}.json` oder `./locales/{locale}/{namespace}.json`.
+export default config;
+```
+
+Alternative: Pro-Locale-Layout, weiterhin schreibgeschützt (nur die ausgewählte Locale wird geladen):
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // Nur Dateien für Locales.FRENCH werden aus diesem Muster geladen
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### Funktionsweise
 
-JSON-Nachrichten pro Locale (oft `./messages/{locale}.json`) oder pro Namespace.
+- Entdecken: Erstellt einen Glob aus Ihrem `source`-Builder und sammelt passende JSON-Dateien.
+- Importieren: Lädt jede JSON-Datei als Intlayer-Wörterbuch mit der angegebenen `locale`.
+- Schreibgeschützt: Schreibt oder formatiert keine Ausgabedateien; verwenden Sie `syncJSON`, wenn Sie eine Roundtrip-Synchronisierung benötigen.
+- Auto-Fill bereit: Definiert ein `fill`-Muster, sodass `intlayer content fill` fehlende Schlüssel füllen kann.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // Erstellt Pfade zu Ihren JSON-Dateien. `locale` ist optional, wenn Ihre Struktur kein Locale-Segment hat
+  source: ({ key, locale }) => string,
+
+  // Ziel-Locale für die von dieser Plugin-Instanz geladenen Wörterbücher
+  // Standardmäßig configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Optionales Label zur Identifizierung der Quelle
+  location?: string, // Standard: "plugin"
+
+  // Priorität zur Konfliktlösung gegenüber anderen Quellen
+  priority?: number, // Standard: 0
+
+  // Optionaler Formatierer für den JSON-Inhalt
+  format?: 'intlayer' | 'icu' | 'i18next', // Standard: 'intlayer'
+
+  // Teilt eine einzelne Datei in ein Wörterbuch pro Top-Level-Schlüssel (automatisch erkannt)
+  splitKeys?: boolean,
+});
 ```
 
-Siehe auch: `docs/de/intlayer_with_next-intl.md`.
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+Gibt den Formatierer an, der für den Wörterbuchinhalt beim Laden von JSON-Dateien verwendet werden soll. Dies ermöglicht die Verwendung verschiedener Nachrichtenformatierungssyntaxen, die mit verschiedenen i18n-Bibliotheken kompatibel sind.
 
-Einzelne JSON-Datei pro Locale ist üblich:
+- `'intlayer'`: Der Standard-Intlayer-Formatierer (Standard).
+- `'icu'`: Verwendet ICU-Nachrichtenformatierung (kompatibel mit Bibliotheken wie react-intl, vue-i18n).
+- `'i18next'`: Verwendet i18next-Nachrichtenformatierung (kompatibel mit i18next, next-i18next, Solid-i18next).
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**Beispiel:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // ICU-Formatierung für Kompatibilität verwenden
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-Entweder eine einzelne Datei pro Locale oder pro Namespace:
+Gleiches Verhalten wie bei [`syncJSON`](#splitkeys-boolean): Wenn eine einzelne JSON-Datei mehrere Namespaces durch ihre Top-Level-Schlüssel gruppiert, wird jeder Top-Level-Schlüssel zu einem eigenen Wörterbuch.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (Standard): **automatisch erkannt** — Aufteilung, wenn das `source`-Muster kein `{key}`-Segment enthält, andernfalls ein einzelnes Wörterbuch.
+- `true` / `false`: Aufteilung erzwingen oder deaktivieren.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys automatisch aktiviert: `Hero`, `Nav`, `About`, … jeder wird zu einem Wörterbuch
+}),
 ```
 
+### Verhalten und Konventionen
+
+- Wenn Ihre `source`-Maske einen Locale-Platzhalter enthält, werden nur Dateien für die ausgewählte `locale` importiert.
+- Wenn in Ihrer Maske kein `{key}`-Segment vorhanden ist, wird jeder Top-Level-Schlüssel der Datei standardmäßig zu einem eigenen Wörterbuch (siehe [`splitKeys`](#splitkeys-boolean)). Setzen Sie `splitKeys: false`, um stattdessen die gesamte Datei als ein einziges `index`-Wörterbuch zu laden.
+- Schlüssel werden aus Dateipfaden abgeleitet, indem der `{key}`-Platzhalter in Ihrem `source`-Builder ersetzt wird.
+- Das Plugin verwendet nur entdeckte Dateien und erstellt keine fehlenden Locales oder Schlüssel.
+- Der `fill`-Pfad wird aus Ihrer `source` abgeleitet und verwendet, um fehlende Werte über die CLI zu aktualisieren, wenn Sie sich dafür entscheiden.
+
+## Konfliktlösung
+
+Wenn derselbe Übersetzungsschlüssel in mehreren JSON-Quellen vorhanden ist:
+
+1. Bestimmt das Plugin mit der höchsten Priorität den endgültigen Wert
+2. Werden Quellen mit niedrigerer Priorität als Fallbacks für fehlende Schlüssel verwendet
+3. Ermöglicht es Ihnen, Legacy-Übersetzungen beizubehalten und gleichzeitig schrittweise auf neue Strukturen umzusteigen
+
 ## CLI
 
 Die synchronisierten JSON-Dateien werden wie andere `.content`-Dateien behandelt. Das bedeutet, dass alle intlayer-Befehle für die synchronisierten JSON-Dateien verfügbar sind. Einschließlich:

package/docs/en/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Sync JSON plugin
 description: Synchronize Intlayer dictionaries with third‑party i18n JSON files (i18next, next-intl, react-intl, vue-i18n, and more). Keep your existing i18n while using Intlayer to manage, translate, and test your messages.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Add splitKeys option (one dictionary per top-level namespace key) for next-intl / react-intl single-file layouts"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Add ICU and i18next format support"
@@ -182,6 +185,7 @@ syncJSON({
   location?: string, // optional label, default: "plugin"
   priority?: number, // optional priority for conflict resolution, default: 0
   format?: 'intlayer' | 'icu' | 'i18next', // optional formatter, used for intlayer runtime compatibility
+  splitKeys?: boolean, // optional, split a single file into one dictionary per top-level key (auto-detected)
 });
 ```
 
@@ -206,6 +210,38 @@ syncJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Controls whether a single JSON file whose **first-level keys are namespaces** should become one dictionary per top-level key, instead of a single dictionary holding the whole file.
+
+This matches the namespace model of libraries like `next-intl` and `react-intl`, where one `messages/{locale}.json` file groups several namespaces by its first-level keys, each addressed independently (e.g. `useTranslations('Hero')` resolves to the `Hero` dictionary).
+
+- `undefined` (default): **auto-detected** — the file is split when the `source` pattern has no `{key}` segment (one file holds every namespace), and kept as a single dictionary otherwise (one file per key).
+- `true`: always split each top-level key into its own dictionary.
+- `false`: never split; the whole file becomes a single dictionary.
+
+Given a single `messages/{locale}.json` file:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // implied because the pattern has no `{key}` segment
+}),
+```
+
+This produces three dictionaries — `Hero`, `Nav`, and `About` — so `useTranslations('Hero')` (next-intl) resolves correctly. On write-back, all namespaces are re-assembled into the same per-locale file.
+
+> When you keep the explicit `{key}` segment in your `source` (e.g. `./locales/${locale}/${key}.json`), each file is already one namespace, so splitting is disabled by default.
+
 ### Multiple JSON sources and priority
 
 You can add multiple `syncJSON` plugins to synchronize different JSON sources. This is useful when you have multiple i18n libraries or different JSON structures in your project.
@@ -338,6 +374,9 @@ loadJSON({
 
   // Optional formatter for the JSON content
   format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Split a single file into one dictionary per top-level key (auto-detected)
+  splitKeys?: boolean,
 });
 ```
 
@@ -359,10 +398,25 @@ loadJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Same behavior as in [`syncJSON`](#splitkeys-boolean): when a single JSON file groups several namespaces by its first-level keys, each top-level key becomes its own dictionary.
+
+- `undefined` (default): **auto-detected** — split when the `source` pattern has no `{key}` segment, single dictionary otherwise.
+- `true` / `false`: force or disable splitting.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
+```
+
 ### Behavior and conventions
 
 - If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.
-- If there is no `{key}` segment in your mask, the dictionary key is "index".
+- If there is no `{key}` segment in your mask, each top-level key of the file becomes its own dictionary by default (see [`splitKeys`](#splitkeys-boolean)). Set `splitKeys: false` to instead load the whole file as a single `index` dictionary.
 - Keys are derived from file paths by substituting the `{key}` placeholder in your `source` builder.
 - The plugin only uses discovered files and does not fabricate missing locales or keys.
 - The `fill` path is inferred from your `source` and used to update missing values via CLI when you opt‑in.