@intlayer/docs 7.0.5 → 7.0.6

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

@@ -55,15 +55,68 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Quick start
+## Plugins
+
+This package provides two plugins:
+
+- `loadJSON`: Load JSON files into Intlayer dictionaries.
+  - This plugin is used to load JSON files from a source and will be loaded into Intlayer dictionaries. It can scan all the codebase and search for specific JSON files.
+    This plugin can be used
+    - if you use an i18n library that impose a specific location for your JSON to be loaded (ex: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, etc.), but you want to place your content declaration where you want in your code base.
+    - It can also be used if you want to fetch your messages from a remote source (ex: a CMS, a API, etc.) and store your messages in JSON files.
+
+  > Under the hood, this plugin will scan all the codebase and search for specific JSON files and load them into Intlayer dictionaries.
+  > Note that this plugin will not write the output and translations back to the JSON files.
+
+- `syncJSON`: Synchronize JSON files with Intlayer dictionaries.
+  - This plugin is used to synchronize JSON files with Intlayer dictionaries. It can scan the given location and load the JSON that match the pattern for specific JSON files. This plugin is useful if you want to get the benefits of Intlayer while using another i18n library.
+
+## Using both 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,
+  },
+
+  // Keep your current JSON files in sync with Intlayer dictionaries
+  plugins: [
+    /**
+     * Will load all the JSON files in the src that match the pattern {key}.i18n json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Ensures these JSON files take precedence over files at `./locales/en/${key}.json`
+    }),
+    /**
+     * Will load, and write the output and translations back to the JSON files in the locales directory
+     */
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Quick start
 
 Add the plugin to your `intlayer.config.ts` and point it at your existing JSON structure.
 
 ```ts fileName="intlayer.config.ts"
-import { defineConfig, Locales } from "intlayer";
+import { Locales, type IntlayerConfig } from "intlayer";
 import { syncJSON } from "@intlayer/sync-json-plugin";
 
-export default defineConfig({
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
@@ -76,20 +129,33 @@ export default defineConfig({
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
     }),
   ],
-});
+};
+
+export default config;
 ```
 
 Alternative: single file per locale (common with 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({
+      source: ({ locale }) => `./locales/${locale}.json`,
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### How it works
+#### How it works
 
 - Read: the plugin discovers JSON files from your `source` builder and loads them as Intlayer dictionaries.
 - Write: after builds and fills, it writes localized JSON back to the same paths (with a final newline to avoid formatting issues).
@@ -105,24 +171,24 @@ syncJSON({
 });
 ```
 
-## Multiple JSON sources and priority
+### 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.
 
-### Priority system
+#### Priority system
 
 When multiple plugins target the same dictionary key, the `priority` parameter determines which plugin takes precedence:
 
 - Higher priority numbers win over lower ones
 - Default priority of `.content` files is `0`
-- Default priority of plugins content files is `-1`
+- Default priority of plugins is `0`
 - Plugins with the same priority are processed in the order they appear in the configuration
 
 ```ts fileName="intlayer.config.ts"
-import { defineConfig, Locales } from "intlayer";
+import { Locales, type IntlayerConfig } from "intlayer";
 import { syncJSON } from "@intlayer/sync-json-plugin";
 
-export default defineConfig({
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH],
     defaultLocale: Locales.ENGLISH,
@@ -150,74 +216,105 @@ export default defineConfig({
       priority: 1,
     }),
   ],
-});
+};
+
+export default config;
 ```
 
-### Conflict resolution
+## Load JSON plugin
 
-When the same translation key exists in multiple JSON sources:
+### Quick start
 
-1. The plugin with the highest priority determines the final value
-2. Lower priority sources are used as fallbacks for missing keys
-3. This allows you to maintain legacy translations while gradually migrating to new structures
+Add the plugin to your `intlayer.config.ts` to ingest existing JSON files as Intlayer dictionaries. This plugin is read‑only (no writes to disk):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-## Integrations
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-Below are common mappings. Keep your runtime untouched; only add the plugin.
+  plugins: [
+    // Ingest JSON messages located anywhere in your source tree
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Load a single locale per plugin instance (defaults to the config defaultLocale)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-### i18next
+export default config;
+```
 
-Typical file layout: `./public/locales/{locale}/{namespace}.json` or `./locales/{locale}/{namespace}.json`.
+Alternative: per‑locale layout, still read‑only (only the selected locale is loaded):
 
 ```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({
+    loadJSON({
+      // Only files for Locales.FRENCH will be loaded from this pattern
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### How it works
 
-Per‑locale JSON messages (often `./messages/{locale}.json`) or per‑namespace.
+- Discover: builds a glob from your `source` builder and collects matching JSON files.
+- Ingest: loads each JSON file as an Intlayer dictionary with the provided `locale`.
+- Read‑only: does not write or format output files; use `syncJSON` if you need round‑trip sync.
+- Auto‑fill ready: defines a `fill` pattern so `intlayer content fill` can populate missing keys.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
-```
+### API
 
-See also: `docs/en/intlayer_with_next-intl.md`.
+```ts
+loadJSON({
+  // Build paths to your JSON. `locale` is optional if your structure has no locale segment
+  source: ({ key, locale }) => string,
 
-### react-intl
+  // Target locale for the dictionaries loaded by this plugin instance
+  // Defaults to configuration.internationalization.defaultLocale
+  locale?: Locale,
 
-Single JSON per locale is common:
+  // Optional label to identify the source
+  location?: string, // default: "plugin"
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+  // Priority used for conflict resolution against other sources
+  priority?: number, // default: 0
+});
 ```
 
-### vue-i18n
+### Behavior and conventions
 
-Either a single file per locale or per‑namespace:
+- 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".
+- 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.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
-```
+## Conflict resolution
+
+When the same translation key exists in multiple JSON sources:
+
+1. The plugin with the highest priority determines the final value
+2. Lower priority sources are used as fallbacks for missing keys
+3. This allows you to maintain legacy translations while gradually migrating to new structures
 
 ## CLI
 

package/docs/en/releases/v7.md

@@ -31,7 +31,7 @@ Welcome to Intlayer v7! This major release introduces significant improvements i
 - Improved TypeScript type generation with locale-specific types
 - Bundle optimization: Locales as strings instead of enum
 - New routing modes: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
-- GDPR-compliant locale storage with localStorage as default
+- GDPR-compliant using localStorage
 - Flexible storage configuration: cookies, localStorage, sessionStorage, or multiple
 - 30% smaller Visual Editor package size
 - Enhanced middleware configuration options

package/docs/en-GB/intlayer_with_nextjs_15.md

@@ -998,19 +998,28 @@ const sitemap = (): MetadataRoute.Sitemap => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];
@@ -1025,19 +1034,28 @@ const sitemap = () => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];
@@ -1052,19 +1070,28 @@ const sitemap = () => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];

package/docs/en-GB/intlayer_with_nextjs_16.md

@@ -1063,19 +1063,28 @@ const sitemap = (): MetadataRoute.Sitemap => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];
@@ -1090,19 +1099,28 @@ const sitemap = () => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];
@@ -1117,19 +1135,28 @@ const sitemap = () => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];

package/docs/en-GB/releases/v7.md

@@ -30,7 +30,7 @@ Welcome to Intlayer v7! This major release introduces significant improvements i
 - Improved TypeScript type generation with locale-specific types
 - Bundle optimisation: Locales as strings instead of enum
 - New routing modes: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
-- GDPR-compliant locale storage with localStorage as default
+- GDPR-compliant using localStorage
 - Flexible storage configuration: cookies, localStorage, sessionStorage, or multiple
 - 30% smaller Visual Editor package size
 - Enhanced middleware configuration options

package/docs/es/intlayer_with_nextjs_15.md

@@ -970,19 +970,28 @@ const sitemap = (): MetadataRoute.Sitemap => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];
@@ -997,19 +1006,28 @@ const sitemap = () => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];
@@ -1024,19 +1042,28 @@ const sitemap = () => [
   {
     url: "https://example.com",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com") },
+      languages: {
+        ...getMultilingualUrls("https://example.com"),
+        "x-default": "https://example.com",
+      },
     },
   },
   {
     url: "https://example.com/login",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/login") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/login"),
+        "x-default": "https://example.com/login",
+      },
     },
   },
   {
     url: "https://example.com/register",
     alternates: {
-      languages: { ...getMultilingualUrls("https://example.com/register") },
+      languages: {
+        ...getMultilingualUrls("https://example.com/register"),
+        "x-default": "https://example.com/register",
+      },
     },
   },
 ];