@intlayer/docs 7.0.3 → 7.0.4

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

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+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:
+  - Intlayer
+  - Sync JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - Übersetzungen
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Erste Dokumentation des Sync JSON Plugins
+---
+
+# Sync JSON (i18n-Brücken)
+
+Verwenden Sie Intlayer als Ergänzung zu Ihrem bestehenden i18n-Stack. Dieses Plugin hält Ihre JSON-Nachrichten mit den Intlayer-Wörterbüchern synchron, sodass Sie:
+
+- i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n usw. beibehalten können.
+- Ihre Nachrichten mit Intlayer (CLI, CI, Anbieter, CMS) verwalten und übersetzen, ohne Ihre App umzustrukturieren.
+- Tutorials und SEO-Inhalte für jedes Ökosystem bereitstellen und gleichzeitig Intlayer als JSON-Verwaltungsschicht vorschlagen.
+
+Hinweise und aktueller Umfang:
+
+- Die Externalisierung zum CMS funktioniert für Übersetzungen und klassischen Text.
+- Noch keine Unterstützung für Einfügungen, Pluralformen/ICU oder erweiterte Laufzeitfunktionen anderer Bibliotheken.
+- Der visuelle Editor wird für Ausgaben von Drittanbieter-i18n noch nicht unterstützt.
+
+### Wann Sie dieses Plugin verwenden sollten
+
+- Sie verwenden bereits eine i18n-Bibliothek und speichern Nachrichten in JSON-Dateien.
+- Sie möchten KI-unterstütztes Ausfüllen, Tests in CI und Content-Operationen durchführen, ohne Ihre Rendering-Laufzeit zu ändern.
+
+## Installation
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# oder
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Schnellstart
+
+Fügen Sie das Plugin zu Ihrer `intlayer.config.ts` hinzu und verweisen Sie auf Ihre bestehende JSON-Struktur.
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  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: [
+    syncJSON({
+      // Pro-Locale, pro-Namespace Layout (z.B. next-intl, i18next mit Namespaces)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+Alternative: Einzelne Datei pro Locale (häufig bei i18next/react-intl Setups):
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### 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).
+- Auto-Fill: Das Plugin deklariert einen `autoFill`-Pfad für jedes Wörterbuch. Das Ausführen von `intlayer fill` aktualisiert standardmäßig nur fehlende Übersetzungen in Ihren JSON-Dateien.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // erforderlich
+  location?: string, // optionales Label, Standard: "plugin"
+  priority?: number, // optionale Priorität zur Konfliktlösung, Standard: 0
+});
+```
+
+## 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
+
+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`
+- Plugins mit derselben Priorität werden in der Reihenfolge verarbeitet, in der sie in der Konfiguration erscheinen
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Primäre JSON-Quelle (höchste Priorität)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Fallback-JSON-Quelle (niedrigere Priorität)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Legacy-JSON-Quelle (niedrigste Priorität)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### 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
+
+## Integrationen
+
+Nachfolgend sind gängige Zuordnungen aufgeführt. Belassen Sie Ihre Laufzeit unverändert; fügen Sie nur das Plugin hinzu.
+
+### i18next
+
+Typische Dateistruktur: `./public/locales/{locale}/{namespace}.json` oder `./locales/{locale}/{namespace}.json`.
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+```
+
+### next-intl
+
+JSON-Nachrichten pro Locale (oft `./messages/{locale}.json`) oder pro Namespace.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+Siehe auch: `docs/de/intlayer_with_next-intl.md`.
+
+### react-intl
+
+Einzelne JSON-Datei pro Locale ist üblich:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+Entweder eine einzelne Datei pro Locale oder pro Namespace:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+  }),
+];
+```
+
+## 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:
+
+- `intlayer content test`, um zu testen, ob Übersetzungen fehlen
+- `intlayer content list`, um die synchronisierten JSON-Dateien aufzulisten
+- `intlayer content fill`, um fehlende Übersetzungen zu ergänzen
+- `intlayer content push`, um die synchronisierten JSON-Dateien zu pushen
+- `intlayer content pull`, um die synchronisierten JSON-Dateien zu pullen
+
+Siehe [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/intlayer_cli.md) für weitere Details.
+
+## Einschränkungen (aktuell)
+
+- Keine Unterstützung für Einfügungen oder Pluralformen/ICU bei der Verwendung von Drittanbieter-Bibliotheken.
+- Visueller Editor ist für Nicht-Intlayer-Laufzeiten noch nicht verfügbar.
+- Nur JSON-Synchronisierung; Nicht-JSON-Katalogformate werden nicht unterstützt.
+
+## Warum das wichtig ist
+
+- Wir können etablierte i18n-Lösungen empfehlen und Intlayer als Zusatzmodul positionieren.
+- Wir nutzen deren SEO/Schlüsselwörter mit Tutorials, die abschließend vorschlagen, Intlayer zur Verwaltung von JSON einzusetzen.
+- Erweitert die ansprechbare Zielgruppe von „neuen Projekten“ auf „jedes Team, das bereits i18n verwendet“.

package/docs/de/releases/v7.md

@@ -411,23 +411,6 @@ Das System führt automatisch aus:
 
 **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: {
@@ -439,7 +422,7 @@ export default {
     noPrefix: false,
   },
 };
-````
+```
 
 **Nachher (v7):**
 

package/docs/en/CI_CD.md

@@ -27,7 +27,7 @@ Intlayer allows the automatic generation of translations for your content declar
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## Using the CMS
 

package/docs/en/configuration.md

@@ -59,7 +59,7 @@ Intlayer configuration files allow customization of various aspects of the plugi
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ---
 

package/docs/en/formatters.md

@@ -46,7 +46,7 @@ history:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## Overview
 

package/docs/en/how_works_intlayer.md

@@ -23,7 +23,7 @@ history:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## Overview
 

package/docs/en/intlayer_CMS.md

@@ -41,7 +41,7 @@ For that, Intlayer introduce the concept of 'distant dictionaries'.
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ---
 

package/docs/en/intlayer_cli.md

@@ -52,7 +52,7 @@ history:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ---
 
@@ -150,6 +150,10 @@ This command will find your declaration content files as default as `./src/**/*.
 
   > Example: `npx intlayer build --skip-prepare`
 
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
 ### Watch dictionaries
 
 ```bash
@@ -203,6 +207,10 @@ If [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/
 
   > Example: `npx intlayer dictionary push --env-file .env.production.local`
 
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
 **Environment variables options:**
 
 - **`--env`**: Specify the environment (e.g., `development`, `production`). Useful in the case you use environment variables in your intlayer configuration file.
@@ -279,6 +287,10 @@ If [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/
 
   > Example: `npx intlayer dictionary push --env-file .env.production.local`
 
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
 **Environment variables options:**
 
 - **`--env`**: Specify the environment (e.g., `development`, `production`).
@@ -392,6 +404,10 @@ This command analyzes your content declaration files for potential issues such a
 
   > Example: `npx intlayer fill --base-dir ./src`
 
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
 **Preparation options:**
 
 - **`--build`**: Build the dictionaries before pushing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
@@ -448,6 +464,10 @@ Total missing required locales: 0
 
   > Example: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
 
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
 **Preparation options:**
 
 - **`--build`**: Build the dictionaries before pushing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
@@ -530,6 +550,7 @@ npx intlayer configuration get
 - **`--env-file`**: Provide a custom environment file to load variables from.
 - **`--base-dir`**: Specify the base directory for the project.
 - **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI)
+- **`--no-cache`**: Disable the cache.
 
 #### Push Configuration
 
@@ -550,6 +571,7 @@ npx intlayer configuration push
 - **`--env-file`**: Provide a custom environment file to load variables from.
 - **`--base-dir`**: Specify the base directory for the project.
 - **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI)
+- **`--no-cache`**: Disable the cache.
 
 By pushing the configuration, your project is fully integrated with the Intlayer CMS, enabling seamless dictionary management across teams.
 
@@ -623,6 +645,7 @@ npx intlayer doc translate
 - **`--env`**: Specify the environment (e.g., `development`, `production`).
 - **`--env-file [envFile]`**: Provide a custom environment file to load variables from.
 - **`--base-dir`**: Specify the base directory for the project.
+- **`--no-cache`**: Disable the cache.
 
   > Example: `npx intlayer doc translate --base-dir ./docs --env-file .env.production.local`
 
@@ -738,6 +761,8 @@ Live Sync lets your app reflect CMS content changes at runtime. No rebuild or re
 
 - **`--base-dir`**: Specify the base directory for the project. To retrieve the intlayer configuration, the command will look for the `intlayer.config.{ts,js,json,cjs,mjs}` file in the base directory.
 
+- **`--no-cache`**: Disable the cache.
+
   > Example: `npx intlayer dictionary push --env-file .env.production.local`
 
 **Log options:**

package/docs/en/intlayer_with_nextjs_14.md

@@ -40,7 +40,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-next-14-templa
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 
@@ -1488,6 +1488,8 @@ yarn add @intlayer/swc --save-dev
 
 > Note: This package is not installed by default because SWC plugins are still experimental on Next.js. It may change in the future.
 
+> Note: If you set the option as `importMode: 'dynamic'` or `importMode: 'live'`, it will rely on Suspense, so you will have to wrap your `useIntlayer` calls in a `Suspense` boundary. That means, you will not be able to use the `useIntlayer` directly at the top level of your Page / Layout component.
+
 ### Configure TypeScript
 
 Intlayer use module augmentation to get benefits of TypeScript and make your codebase stronger.

package/docs/en/intlayer_with_nextjs_15.md

@@ -49,7 +49,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-next-15-templa
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 
@@ -1550,6 +1550,8 @@ yarn add @intlayer/swc --save-dev
 
 > Note: This package is not installed by default because SWC plugins are still experimental on Next.js. It may change in the future.
 
+> Note: If you set the option as `importMode: 'dynamic'` or `importMode: 'live'`, it will rely on Suspense, so you will have to wrap your `useIntlayer` calls in a `Suspense` boundary. That means, you will not be able to use the `useIntlayer` directly at the top level of your Page / Layout component.
+
 ### Watch dictionaries changes on Turbopack
 
 When using Turbopack as your development server with the `next dev --turbopack` command, dictionary changes will not be automatically detected by default.

package/docs/en/intlayer_with_nextjs_16.md

@@ -30,7 +30,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-next-16-templa
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 
@@ -1525,6 +1525,8 @@ yarn add @intlayer/swc --save-dev
 
 > Note: This package is not installed by default because SWC plugins are still experimental on Next.js. It may change in the future.
 
+> Note: If you set the option as `importMode: 'dynamic'` or `importMode: 'live'`, it will rely on Suspense, so you will have to wrap your `useIntlayer` calls in a `Suspense` boundary. That means, you will not be able to use the `useIntlayer` directly at the top level of your Page / Layout component.
+
 ### Watch dictionaries changes on Turbopack
 
 When using Turbopack as your development server with the `next dev` command, dictionary changes will not be automatically detected by default.

package/docs/en/intlayer_with_nextjs_page_router.md

@@ -29,7 +29,7 @@ history:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_nuxt.md

@@ -27,7 +27,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-nuxt-template)
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_react_native+expo.md

@@ -30,7 +30,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-react-native-t
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_react_router_v7.md

@@ -33,7 +33,7 @@ This guide demonstrates how to integrate **Intlayer** for seamless international
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_tanstack.md

@@ -30,7 +30,7 @@ history:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 This guide demonstrates how to integrate **Intlayer** for seamless internationalization in Tanstack Start projects with locale-aware routing, TypeScript support, and modern development practices.
 

package/docs/en/intlayer_with_vite+preact.md

@@ -32,7 +32,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-vite-preact-te
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_vite+react.md

@@ -31,7 +31,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-vite-react-tem
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_vite+solid.md

@@ -44,7 +44,7 @@ With Intlayer, you can:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ### Step 1: Install Dependencies
 

package/docs/en/intlayer_with_vite+svelte.md

@@ -29,7 +29,7 @@ history:
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

package/docs/en/intlayer_with_vite+vue.md

@@ -27,7 +27,7 @@ See [Application Template](https://github.com/aymericzip/intlayer-vite-vue-templ
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## What is Intlayer?
 

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

@@ -28,7 +28,7 @@ history:
     changes: Initial Sync JSON plugin documentation
 ---
 
-## Sync JSON (i18n bridges)
+# Sync JSON (i18n bridges)
 
 Use Intlayer as an add‑on to your existing i18n stack. This plugin keeps your JSON messages in sync with Intlayer dictionaries so you can:
 

package/docs/en/roadmap.md

@@ -33,7 +33,7 @@ Intlayer is a content management and internationalization solution designed to s
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ---