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

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Plugin de sincronización JSON
 description: Sincroniza los diccionarios de Intlayer con archivos JSON i18n de terceros (i18next, next-intl, react-intl, vue-i18n y más). Mantén tu i18n existente mientras usas Intlayer para gestionar, traducir y probar tus mensajes.
 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: "Añadida opción splitKeys (un diccionario por clave de espacio de nombres de nivel superior) para diseños de archivo único de next-intl / react-intl"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Añadido soporte para formatos ICU e i18next"
@@ -62,7 +65,63 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Inicio rápido
+## Plugins
+
+Este paquete proporciona dos plugins:
+
+- `loadJSON`: Carga archivos JSON en diccionarios de Intlayer.
+  - Este plugin se utiliza para cargar archivos JSON desde una fuente y se cargará en los diccionarios de Intlayer. Puede escanear toda la base de código y buscar archivos JSON específicos.
+    Este plugin se puede utilizar
+    - si utilizas una biblioteca i18n que impone una ubicación específica para que se carguen tus JSON (ej: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, etc.), pero quieres colocar tu declaración de contenido donde quieras en tu base de código.
+    - También se puede utilizar si quieres obtener tus mensajes de una fuente remota (ej: un CMS, una API, etc.) y almacenar tus mensajes en archivos JSON.
+
+  > Bajo el capó, este plugin escaneará toda la base de código y buscará archivos JSON específicos y los cargará en los diccionarios de Intlayer.
+  > Ten en cuenta que este plugin no escribirá la salida y las traducciones de vuelta a los archivos JSON.
+
+- `syncJSON`: Sincroniza archivos JSON con diccionarios de Intlayer.
+  - Este plugin se utiliza para sincronizar archivos JSON con diccionarios de Intlayer. Puede escanear la ubicación dada y cargar los JSON que coincidan con el patrón para archivos JSON específicos. Este plugin es útil si quieres obtener los beneficios de Intlayer mientras usas otra biblioteca i18n.
+
+## Usando ambos plugins
+
+```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,
+  },
+
+  // Mantén tus archivos JSON actuales sincronizados con los diccionarios de Intlayer
+  plugins: [
+    /**
+     * Cargará todos los archivos JSON en src que coincidan con el patrón {key}.i18n json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Asegura que estos archivos JSON tengan precedencia sobre los archivos en `./locales/en/${key}.json`
+      format: "intlayer", // Formato del contenido JSON
+    }),
+    /**
+     * Cargará y escribirá la salida y las traducciones de vuelta a los archivos JSON en el directorio locales
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Inicio rápido
 
 Agrega el plugin a tu `intlayer.config.ts` y apúntalo a tu estructura JSON existente.
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Diseño por idioma, por espacio de nombres (por ejemplo, next-intl, i18next con espacios de nombres)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,27 @@ export default config;
 Alternativa: archivo único por idioma (común en configuraciones i18next/react-intl):
 
 ```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;
 ```
 
-### Cómo funciona
+#### Cómo funciona
 
 - Lectura: el plugin descubre archivos JSON desde tu generador `source` y los carga como diccionarios de Intlayer.
 - Escritura: después de las compilaciones y llenados, escribe los JSON localizados de vuelta en las mismas rutas (con una nueva línea final para evitar problemas de formato).
@@ -112,6 +185,7 @@ syncJSON({
   location?: string, // etiqueta opcional, por defecto: "plugin"
   priority?: number, // prioridad opcional para resolución de conflictos, por defecto: 0
   format?: 'intlayer' | 'icu' | 'i18next', // formateador opcional, usado para compatibilidad con el runtime de Intlayer
+  splitKeys?: boolean, // opcional, divide un solo archivo en un diccionario por clave de espacio de nombres de nivel superior (autodetectado)
 });
 ```
 
@@ -136,17 +210,49 @@ syncJSON({
 }),
 ```
 
-## Múltiples fuentes JSON y prioridad
+#### `splitKeys` (boolean)
+
+Controla si un único archivo JSON cuyas **claves de primer nivel son espacios de nombres** debe convertirse en un diccionario por cada clave de nivel superior, en lugar de un único diccionario que contenga todo el archivo.
+
+Esto coincide con el modelo de espacio de nombres de bibliotecas como `next-intl` y `react-intl`, donde un archivo `messages/{locale}.json` agrupa varios espacios de nombres por sus claves de primer nivel, cada uno abordado de forma independiente (por ejemplo, `useTranslations('Hero')` se resuelve en el diccionario `Hero`).
+
+- `undefined` (por defecto): **autodetectado** — el archivo se divide cuando el patrón `source` no tiene un segmento `{key}` (un archivo contiene todos los espacios de nombres), y se mantiene como un único diccionario en caso contrario (un archivo por clave).
+- `true`: siempre divide cada clave de nivel superior en su propio diccionario.
+- `false`: nunca divide; todo el archivo se convierte en un único diccionario.
+
+Dado un único archivo `messages/{locale}.json`:
+
+```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, // implícito porque el patrón no tiene un segmento `{key}`
+}),
+```
+
+Esto produce tres diccionarios — `Hero`, `Nav` y `About` — por lo que `useTranslations('Hero')` (next-intl) se resuelve correctamente. Al volver a escribir, todos los espacios de nombres se reensamblan en el mismo archivo por localidad.
+
+> Cuando mantienes el segmento `{key}` explícito en tu `source` (por ejemplo, `./locales/${locale}/${key}.json`), cada archivo ya es un espacio de nombres, por lo que la división está deshabilitada por defecto.
+
+### Múltiples fuentes JSON y prioridad
 
 Puedes agregar múltiples plugins `syncJSON` para sincronizar diferentes fuentes JSON. Esto es útil cuando tienes múltiples bibliotecas i18n o diferentes estructuras JSON en tu proyecto.
 
-### Sistema de prioridad
+#### Sistema de prioridad
 
 Cuando múltiples plugins apuntan a la misma clave del diccionario, el parámetro `priority` determina qué plugin tiene precedencia:
 
 - Los números de prioridad más altos ganan sobre los más bajos
 - La prioridad por defecto de los archivos `.content` es `0`
-- La prioridad por defecto de los archivos de contenido de plugins es `-1`
+- La prioridad por defecto de los plugins es `0`
 - Los plugins con la misma prioridad se procesan en el orden en que aparecen en la configuración
 
 ```ts fileName="intlayer.config.ts"
@@ -189,73 +295,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Resolución de conflictos
+## Load JSON plugin
 
-Cuando la misma clave de traducción existe en múltiples fuentes JSON:
+### Inicio rápido
 
-1. El plugin con la prioridad más alta determina el valor final
-2. Las fuentes con menor prioridad se usan como respaldo para claves faltantes
-3. Esto permite mantener traducciones heredadas mientras se migra gradualmente a nuevas estructuras
+Agrega el plugin a tu `intlayer.config.ts` para ingerir archivos JSON existentes como diccionarios de Intlayer. Este plugin es de solo lectura (no escribe en disco):
 
-## Integraciones
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-A continuación se muestran mapeos comunes. Mantén tu entorno de ejecución sin cambios; solo agrega el plugin.
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-### i18next
+  plugins: [
+    // Ingerir mensajes JSON ubicados en cualquier parte de tu árbol de código fuente
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Cargar una sola localidad por instancia de plugin (por defecto a la localidad predeterminada de la configuración)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-Disposición típica de archivos: `./public/locales/{locale}/{namespace}.json` o `./locales/{locale}/{namespace}.json`.
+export default config;
+```
+
+Alternativa: diseño por localidad, aún de solo lectura (solo se carga la localidad seleccionada):
 
 ```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({
+      // Solo los archivos para Locales.FRENCH se cargarán desde este patrón
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### Cómo funciona
 
-Mensajes JSON por localidad (a menudo `./messages/{locale}.json`) o por espacio de nombres.
+- Descubrir: construye un glob a partir de tu generador `source` y recopila los archivos JSON coincidentes.
+- Ingerir: carga cada archivo JSON como un diccionario de Intlayer con la `locale` proporcionada.
+- Solo lectura: no escribe ni formatea archivos de salida; usa `syncJSON` si necesitas sincronización de ida y vuelta.
+- Listo para auto‑relleno: define un patrón `fill` para que `intlayer content fill` pueda rellenar las claves faltantes.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // Construye rutas a tu JSON. `locale` es opcional si tu estructura no tiene un segmento de localidad
+  source: ({ key, locale }) => string,
+
+  // Localidad objetivo para los diccionarios cargados por esta instancia de plugin
+  // Por defecto a configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Etiqueta opcional para identificar la fuente
+  location?: string, // default: "plugin"
+
+  // Prioridad utilizada para la resolución de conflictos contra otras fuentes
+  priority?: number, // default: 0
+
+  // Formateador opcional para el contenido JSON
+  format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Divide un solo archivo en un diccionario por clave de nivel superior (autodetectado)
+  splitKeys?: boolean,
+});
 ```
 
-Véase también: `docs/es/intlayer_with_next-intl.md`.
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+Especifica el formateador a utilizar para el contenido del diccionario al cargar archivos JSON. Esto permite usar diferentes sintaxis de formateo de mensajes compatibles con varias bibliotecas i18n.
 
-Es común un único JSON por localidad:
+- `'intlayer'`: El formateador Intlayer por defecto (por defecto).
+- `'icu'`: Usa el formateo de mensajes ICU (compatible con bibliotecas como react-intl, vue-i18n).
+- `'i18next'`: Usa el formateo de mensajes i18next (compatible con i18next, next-i18next, Solid-i18next).
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**Ejemplo:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Usar formateo ICU para compatibilidad
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-Puede ser un solo archivo por locale o por namespace:
+Mismo comportamiento que en [`syncJSON`](#splitkeys-boolean): cuando un único archivo JSON agrupa varios espacios de nombres por sus claves de primer nivel, cada clave de nivel superior se convierte en su propio diccionario.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (por defecto): **autodetectado** — se divide cuando el patrón `source` no tiene un segmento `{key}`, un único diccionario en caso contrario.
+- `true` / `false`: fuerza o deshabilita la división.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … cada uno se convierte en un diccionario
+}),
 ```
 
+### Comportamiento y convenciones
+
+- Si tu máscara `source` incluye un marcador de posición de localidad, solo se ingieren los archivos para la `locale` seleccionada.
+- Si no hay un segmento `{key}` en tu máscara, cada clave de nivel superior del archivo se convierte en su propio diccionario por defecto (ver [`splitKeys`](#splitkeys-boolean)). Establece `splitKeys: false` para cargar en su lugar todo el archivo como un único diccionario `index`.
+- Las claves se derivan de las rutas de los archivos sustituyendo el marcador de posición `{key}` en tu generador `source`.
+- El plugin solo utiliza los archivos descubiertos y no fabrica localidades o claves faltantes.
+- La ruta `fill` se infiere de tu `source` y se utiliza para actualizar los valores faltantes a través de la CLI cuando optas por ello.
+
+## Resolución de conflictos
+
+Cuando la misma clave de traducción existe en múltiples fuentes JSON:
+
+1. El plugin con la prioridad más alta determina el valor final
+2. Las fuentes con menor prioridad se usan como respaldo para claves faltantes
+3. Esto permite mantener traducciones heredadas mientras se migra gradualmente a nuevas estructuras
+
 ## CLI
 
 Los archivos JSON sincronizados serán considerados como otros archivos `.content`. Eso significa que todos los comandos de intlayer estarán disponibles para los archivos JSON sincronizados. Incluyendo:

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Plugin Sync JSON
 description: Synchronisez les dictionnaires Intlayer avec des fichiers JSON i18n tiers (i18next, next-intl, react-intl, vue-i18n, et plus). Conservez votre i18n existant tout en utilisant Intlayer pour gérer, traduire et tester vos 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: "Ajout de l'option splitKeys (un dictionnaire par clé de namespace de premier niveau) pour les layouts de fichiers uniques next-intl / react-intl"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Ajout du support des formats ICU et i18next"
@@ -62,7 +65,63 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Démarrage rapide
+## Plugins
+
+Ce package fournit deux plugins :
+
+- `loadJSON` : Charge les fichiers JSON dans les dictionnaires Intlayer.
+  - Ce plugin est utilisé pour charger les fichiers JSON d'une source et sera chargé dans les dictionnaires Intlayer. Il peut scanner l'ensemble de la codebase et rechercher des fichiers JSON spécifiques.
+    Ce plugin peut être utilisé
+    - si vous utilisez une bibliothèque i18n qui impose un emplacement spécifique pour le chargement de vos JSON (ex: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, etc.), mais que vous souhaitez placer votre déclaration de contenu où vous le souhaitez dans votre codebase.
+    - Il peut également être utilisé si vous souhaitez récupérer vos messages d'une source distante (ex: un CMS, une API, etc.) et stocker vos messages dans des fichiers JSON.
+
+  > En coulisses, ce plugin scannera l'ensemble de la codebase et recherchera des fichiers JSON spécifiques pour les charger dans les dictionnaires Intlayer.
+  > Notez que ce plugin n'écrira pas la sortie et les traductions dans les fichiers JSON.
+
+- `syncJSON` : Synchronise les fichiers JSON avec les dictionnaires Intlayer.
+  - Ce plugin est utilisé pour synchroniser les fichiers JSON avec les dictionnaires Intlayer. Il peut scanner l'emplacement donné et charger les JSON qui correspondent au modèle pour des fichiers JSON spécifiques. Ce plugin est utile si vous souhaitez bénéficier des avantages d'Intlayer tout en utilisant une autre bibliothèque i18n.
+
+## Utilisation des deux plugins
+
+```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,
+  },
+
+  // Gardez vos fichiers JSON actuels synchronisés avec les dictionnaires Intlayer
+  plugins: [
+    /**
+     * Chargera tous les fichiers JSON dans le dossier src qui correspondent au modèle {key}.i18n.json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Garantit que ces fichiers JSON ont la priorité sur les fichiers à `./locales/en/${key}.json`
+      format: "intlayer", // Format du contenu JSON
+    }),
+    /**
+     * Chargera et écrira la sortie et les traductions dans les fichiers JSON du répertoire locales
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin `syncJSON`
+
+### Démarrage rapide
 
 Ajoutez le plugin à votre `intlayer.config.ts` et pointez-le vers votre structure JSON existante.
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Mise en page par locale, par namespace (par exemple, next-intl, i18next avec namespaces)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,27 @@ export default config;
 Alternative : un seul fichier par locale (courant avec les configurations i18next/react-intl) :
 
 ```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;
 ```
 
-### Comment ça fonctionne
+#### Comment ça fonctionne
 
 - Lecture : le plugin découvre les fichiers JSON à partir de votre générateur `source` et les charge comme des dictionnaires Intlayer.
 - Écriture : après les builds et les remplissages, il écrit les JSON localisés aux mêmes emplacements (avec une nouvelle ligne finale pour éviter les problèmes de formatage).
@@ -112,6 +185,7 @@ syncJSON({
   location?: string, // étiquette optionnelle, par défaut : "plugin"
   priority?: number, // priorité optionnelle pour la résolution des conflits, par défaut : 0
   format?: 'intlayer' | 'icu' | 'i18next', // formateur optionnel, utilisé pour la compatibilité avec le runtime Intlayer
+  splitKeys?: boolean, // optionnel, divise un fichier unique en un dictionnaire par clé de premier niveau (détection automatique)
 });
 ```
 
@@ -136,17 +210,49 @@ syncJSON({
 }),
 ```
 
-## Sources JSON multiples et priorité
+#### `splitKeys` (boolean)
+
+Contrôle si un fichier JSON unique dont les **clés de premier niveau sont des namespaces** doit devenir un dictionnaire par clé de premier niveau, au lieu d'un seul dictionnaire contenant tout le fichier.
+
+Cela correspond au modèle de namespace de bibliothèques comme `next-intl` et `react-intl`, où un fichier `messages/{locale}.json` regroupe plusieurs namespaces par ses clés de premier niveau, chacun étant adressé indépendamment (par exemple, `useTranslations('Hero')` se résout au dictionnaire `Hero`).
+
+- `undefined` (par défaut) : **détection automatique** — le fichier est divisé lorsque le modèle `source` n'a pas de segment `{key}` (un fichier contient tous les namespaces), et conservé comme un seul dictionnaire sinon (un fichier par clé).
+- `true` : divise toujours chaque clé de premier niveau en son propre dictionnaire.
+- `false` : ne divise jamais ; le fichier entier devient un seul dictionnaire.
+
+Étant donné un fichier `messages/{locale}.json` unique :
+
+```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, // implicite car le modèle n'a pas de segment `{key}`
+}),
+```
+
+Cela produit trois dictionnaires — `Hero`, `Nav`, et `About` — de sorte que `useTranslations('Hero')` (next-intl) se résout correctement. Lors de la réécriture, tous les namespaces sont réassemblés dans le même fichier par locale.
+
+> Lorsque vous conservez le segment `{key}` explicite dans votre `source` (par exemple, `./locales/${locale}/${key}.json`), chaque fichier est déjà un namespace, donc la division est désactivée par défaut.
+
+### Sources JSON multiples et priorité
 
 Vous pouvez ajouter plusieurs plugins `syncJSON` pour synchroniser différentes sources JSON. Cela est utile lorsque vous avez plusieurs bibliothèques i18n ou différentes structures JSON dans votre projet.
 
-### Système de priorité
+#### Système de priorité
 
 Lorsque plusieurs plugins ciblent la même clé de dictionnaire, le paramètre `priority` détermine quel plugin a la priorité :
 
 - Les nombres de priorité plus élevés l'emportent sur les plus faibles
 - La priorité par défaut des fichiers `.content` est `0`
-- La priorité par défaut des fichiers de contenu des plugins est `-1`
+- La priorité par défaut des plugins est `0`
 - Les plugins avec la même priorité sont traités dans l'ordre où ils apparaissent dans la configuration
 
 ```ts fileName="intlayer.config.ts"
@@ -189,7 +295,133 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Résolution des conflits
+## Load JSON plugin
+
+### Démarrage rapide
+
+Ajoutez le plugin à votre `intlayer.config.ts` pour ingérer les fichiers JSON existants comme dictionnaires Intlayer. Ce plugin est en lecture seule (pas d'écriture sur le disque) :
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Ingérer les messages JSON situés n'importe où dans votre arborescence source
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Charger une seule locale par instance de plugin (par défaut à la defaultLocale de la config)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternative : disposition par locale, toujours en lecture seule (seule la locale sélectionnée est chargée) :
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    loadJSON({
+      // Seuls les fichiers pour Locales.FRENCH seront chargés à partir de ce modèle
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### How it works
+
+- Discover : construit un glob à partir de votre générateur `source` et collecte les fichiers JSON correspondants.
+- Ingest : charge chaque fichier JSON comme un dictionnaire Intlayer avec la `locale` fournie.
+- Read‑only : n'écrit ni ne formate les fichiers de sortie ; utilisez `syncJSON` si vous avez besoin d'une synchronisation aller-retour.
+- Auto‑fill ready : définit un modèle `fill` afin que `intlayer content fill` puisse remplir les clés manquantes.
+
+### API
+
+```ts
+loadJSON({
+  // Construisez les chemins vers votre JSON. `locale` est optionnel si votre structure n'a pas de segment de locale
+  source: ({ key, locale }) => string,
+
+  // Locale cible pour les dictionnaires chargés par cette instance de plugin
+  // Par défaut à configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Étiquette optionnelle pour identifier la source
+  location?: string, // par défaut : "plugin"
+
+  // Priorité utilisée pour la résolution des conflits avec d'autres sources
+  priority?: number, // par défaut : 0
+
+  // Formateur optionnel pour le contenu JSON
+  format?: 'intlayer' | 'icu' | 'i18next', // par défaut : 'intlayer'
+
+  // Divise un fichier unique en un dictionnaire par clé de premier niveau (détection automatique)
+  splitKeys?: boolean,
+});
+```
+
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Spécifie le formateur à utiliser pour le contenu du dictionnaire lors du chargement des fichiers JSON. Cela permet d'utiliser différentes syntaxes de formatage de messages compatibles avec diverses bibliothèques i18n.
+
+- `'intlayer'` : Le formateur Intlayer par défaut (par défaut).
+- `'icu'` : Utilise le formatage de messages ICU (compatible avec des bibliothèques comme react-intl, vue-i18n).
+- `'i18next'` : Utilise le formatage de messages i18next (compatible avec i18next, next-i18next, Solid-i18next).
+
+**Exemple :**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Utiliser le formatage ICU pour la compatibilité
+}),
+```
+
+#### `splitKeys` (boolean)
+
+Même comportement que dans [`syncJSON`](#splitkeys-boolean) : lorsqu'un fichier JSON unique regroupe plusieurs namespaces par ses clés de premier niveau, chaque clé de premier niveau devient son propre dictionnaire.
+
+- `undefined` (par défaut) : **détection automatique** — divise lorsque le modèle `source` n'a pas de segment `{key}`, dictionnaire unique sinon.
+- `true` / `false` : force ou désactive la division.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
+```
+
+### Behavior and conventions
+
+- Si votre masque `source` inclut un placeholder de locale, seuls les fichiers pour la `locale` sélectionnée sont ingérés.
+- S'il n'y a pas de segment `{key}` dans votre masque, chaque clé de premier niveau du fichier devient son propre dictionnaire par défaut (voir [`splitKeys`](#splitkeys-boolean)). Définissez `splitKeys: false` pour charger plutôt l'ensemble du fichier comme un seul dictionnaire `index`.
+- Les clés sont dérivées des chemins de fichiers en substituant le placeholder `{key}` dans votre générateur `source`.
+- Le plugin n'utilise que les fichiers découverts et ne fabrique pas de locales ou de clés manquantes.
+- Le chemin `fill` est inféré de votre `source` et utilisé pour mettre à jour les valeurs manquantes via la CLI lorsque vous l'activez.
+
+## Résolution des conflits
 
 Lorsque la même clé de traduction existe dans plusieurs sources JSON :