@intlayer/docs 6.1.6-canary.0 → 7.0.0-canary.0

package/docs/en/packages/next-intlayer/useLocale.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2025-10-09
 title: useLocale Hook Documentation | next-intlayer
 description: See how to use the useLocale hook for next-intlayer package
 keywords:
@@ -18,6 +18,13 @@ slugs:
   - packages
   - next-intlayer
   - useLocale
+history:
+  - version: 6.2.0
+    date: 2025-10-09
+    changes: Added docs for `useLocale` hook with `onLocaleChange` option
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # Next.js Integration: `useLocale` Hook Documentation for `next-intlayer`
@@ -112,7 +119,39 @@ const LocaleSwitcher = () => {
 };
 ```
 
-## Parameters and Return Values
+## Parameters
+
+The `useLocale` hook accepts the following parameters:
+
+- **`onLocaleChange`**: A string that determines how the URL should be updated when the locale changes. It can be `"replace"`, `"push"` or `"none"`.
+
+  > Let's take an example:
+  >
+  > 1. You are on `/fr/home`
+  > 2. You navigate to `/fr/about`
+  > 3. You switch to `/es/about`
+  > 4. You click the browser's "back" button
+  >
+  > The behavior will differ based on the `onLocaleChange` value:
+  >
+  > - `undefined`: (default) Only updates the locale in the client context, and set the cookie, without changing the URL.
+  >   -> The "back" button will go to `/fr/home`
+  > - `"replace"`: Replaces the current URL with the new localized URL, and set the cookie.
+  >   -> The "back" button will go to `/es/home`
+  > - `"push"`: Adds the new localized URL to browser history, and set the cookie.
+  >   -> The "back" button will go to `/fr/about`
+  > - `(locale) => void`: Set the cookie and trigger a custom function that will be called when the locale changes.
+  >
+  >   The `undefined` option is the default behavior as we recommend to use the `Link` component to navigate to the new locale.
+  >   Example:
+  >
+  >   ```tsx
+  >   <Link href="/es/about" replace>
+  >     About
+  >   </Link>
+  >   ```
+
+## Return Values
 
 When you invoke the `useLocale` hook, it returns an object containing the following properties:
 
@@ -125,9 +164,3 @@ When you invoke the `useLocale` hook, it returns an object containing the follow
 ## Conclusion
 
 The `useLocale` hook from `next-intlayer` is a crucial tool for managing locales in Next.js applications. It offers an integrated approach to adapt your application for multiple locales by handling locale storage, state management, and URL modifications seamlessly.
-
-## Doc History
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

package/docs/en/packages/react-intlayer/t.md

@@ -17,6 +17,10 @@ slugs:
   - packages
   - react-intlayer
   - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # Documentation: `t` Function in `react-intlayer`
@@ -296,9 +300,3 @@ For more detailed usage and advanced features, refer to the [react-intlayer docu
 ---
 
 **Note**: Remember to set up your `IntlayerProvider` properly to ensure that the current locale is correctly passed down to your components. This is crucial for the `t` function to return the correct translations.
-
-## Doc History
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

package/docs/en/packages/react-intlayer/useDictionary.md

@@ -17,6 +17,10 @@ slugs:
   - package
   - react-intlayer
   - useDictionary
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # React Integration: `useDictionary` Hook Documentation
@@ -64,7 +68,7 @@ The hook accepts two parameters:
 
 ## Dictionary
 
-All dictionary objects should be declared in structured content files to ensure type safety and prevent runtime errors. You can find the [setup instructions here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/get_started.md). Here's an example of content declaration:
+All dictionary objects should be declared in structured content files to ensure type safety and prevent runtime errors. You can find the [setup instructions here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md). Here's an example of content declaration:
 
 ```typescript fileName="./component.content.ts" contentDeclarationFormat="typescript"
 import { t, type Dictionary } from "intlayer";
@@ -279,9 +283,3 @@ Unlike integrations using visual editors, attributes like `buttonTitle.value` do
 - **Localization Updates**: When updating content, ensure all locales are consistent to avoid missing translations.
 
 This documentation focuses on the integration of the `useDictionary` hook, providing a streamlined approach to managing localized content without relying on visual editor functionalities.
-
-## Doc History
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

package/docs/en/packages/react-intlayer/useI18n.md

@@ -19,6 +19,10 @@ slugs:
   - packages
   - react-intlayer
   - useI18n
+history:
+  - version: 6.0.0
+    date: 2025-06-29
+    changes: Initial writing of `useI18n` hook documentation
 ---
 
 # React Integration: `useI18n` Hook Documentation
@@ -66,7 +70,7 @@ This hook accepts two parameters:
 
 ## Dictionary
 
-All dictionary keys must be declared within content declaration files to enhance type safety and prevent errors. [Configuration instructions can be found here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/get_started.md).
+All dictionary keys must be declared within content declaration files to enhance type safety and prevent errors. [Configuration instructions can be found here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
 
 ## Usage Examples in React
 
@@ -244,7 +248,3 @@ When localizing attributes, access the translation values appropriately:
 - **Intlayer Visual Editor**: For a more intuitive content management experience, refer to the visual editor documentation [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md).
 
 This section specifically covers the integration of the `useI18n` hook in React applications, simplifying the localization process and ensuring content consistency across different locales.
-
-## Documentation History
-
-- 6.0.0 - 2025-06-29: Initial writing of `useI18n` hook documentation

package/docs/en/packages/react-intlayer/useIntlayer.md

@@ -18,6 +18,10 @@ slugs:
   - packages
   - react-intlayer
   - useIntlayer
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # React Integration: `useIntlayer` Hook Documentation
@@ -65,7 +69,7 @@ The hook accepts two parameters:
 
 ## Dictionary
 
-All dictionary keys must be declared within content declaration files to enhance type safety and avoid errors. You can find the [setup instructions here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/get_started.md).
+All dictionary keys must be declared within content declaration files to enhance type safety and avoid errors. You can find the [setup instructions here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
 
 ## Example Usage in React
 
@@ -245,9 +249,3 @@ When localizing attributes, access the content values appropriately:
 - **Intlayer Visual Editor**: For a more intuitive content management experience, refer to the visual editor documentation [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md).
 
 This section specifically targets the integration of the `useIntlayer` hook in React applications, simplifying the localization process and ensuring content consistency across different locales.
-
-## Doc History
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

package/docs/en/packages/react-intlayer/useLocale.md

@@ -18,6 +18,10 @@ slugs:
   - packages
   - react-intlayer
   - useLocale
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # React Integration: `useLocale` Hook Documentation
@@ -204,9 +208,3 @@ const LocaleSelector = () => {
 ## Conclusion
 
 The `useLocale` hook from `react-intlayer` is an essential tool for managing locales in your React applications, providing the functionality needed to adapt your application to various international audiences effectively.
-
-## Doc History
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

package/docs/en/per_locale_file.md

@@ -14,6 +14,10 @@ slugs:
   - doc
   - concept
   - per-locale-file
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # Declaration of `Per-Locale` Content Declaration in Intlayer
@@ -313,9 +317,3 @@ console.log(JSON.stringify(intlayer, null, 2));
 ### Automatic Translation Generation
 
 Use the [intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md) to auto-fill missing translations based on your preferred services.
-
-## Doc History
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

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

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+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:
+  - Intlayer
+  - Sync JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - translations
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Initial Sync JSON plugin documentation
+---
+
+## 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:
+
+- Keep i18next, next‑intl, react‑intl, vue‑i18n, next‑translate, nuxt‑i18n, Solid‑i18next, svelte‑i18n, etc.
+- Manage and translate your messages with Intlayer (CLI, CI, providers, CMS), without refactoring your app.
+- Ship tutorials and SEO content targeting each ecosystem, while suggesting Intlayer as the JSON management layer.
+
+Notes and current scope:
+
+- Externalization to the CMS works for translations and classic text.
+- No support yet for insertions, plurals/ICU, or advanced runtime features of other libraries.
+- The visual editor is not supported yet for third‑party i18n outputs.
+
+### When to use this plugin
+
+- You already use an i18n library and store messages in JSON files.
+- You want AI‑assisted fill, test in CI, and content ops without changing your rendering runtime.
+
+## Installation
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# or
+npm i -D @intlayer/sync-json-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 { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Keep your current JSON files in sync with Intlayer dictionaries
+  plugins: [
+    syncJSON({
+      // Per-locale, per-namespace layout (e.g., next-intl, i18next with namespaces)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+Alternative: single file per locale (common with i18next/react-intl setups):
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### 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).
+- Auto‑fill: the plugin declares an `autoFill` path for each dictionary. Running `intlayer fill` updates only missing translations in your JSON files by default.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // required
+  location?: string, // optional label, default: "plugin"
+  priority?: number, // optional priority for conflict resolution, default: 0
+});
+```
+
+## 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
+
+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`
+- 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 { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Primary JSON source (highest priority)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Fallback JSON source (lower priority)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Legacy JSON source (lowest priority)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### 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
+
+## Integrations
+
+Below are common mappings. Keep your runtime untouched; only add the plugin.
+
+### i18next
+
+Typical file layout: `./public/locales/{locale}/{namespace}.json` or `./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
+
+Per‑locale JSON messages (often `./messages/{locale}.json`) or per‑namespace.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+See also: `docs/en/intlayer_with_next-intl.md`.
+
+### react-intl
+
+Single JSON per locale is common:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+Either a single file per locale or per‑namespace:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+  }),
+];
+```
+
+## CLI
+
+The synchronized JSON files will be considered as other `.content` files. That means, all intlayer commands will be available for the synchronized JSON files. Including:
+
+- `intlayer content test` to test if there are missing translations
+- `intlayer content list` to list the synchronized JSON files
+- `intlayer content fill` to fill the missing translations
+- `intlayer content push` to push the synchronized JSON files
+- `intlayer content pull` to pull the synchronized JSON files
+
+See [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md) for more details.
+
+## Limitations (current)
+
+- No insertions or plurals/ICU support when targeting third‑party libraries.
+- Visual editor is not available for non‑Intlayer runtimes yet.
+- JSON synchronization only; non‑JSON catalog formats are not supported.
+
+## Why this matters
+
+- We can recommend established i18n solutions and position Intlayer as an add‑on.
+- We leverage their SEO/keywords with tutorials that end by suggesting Intlayer to manage JSON.
+- Expands the addressable audience from “new projects” to “any team already using i18n”.

package/docs/en/releases/v6.md

@@ -277,6 +277,7 @@ To work around this, we dropped the `intlayer watch` command, using the `--with`
 - Prefer the new global `content.autoFill` option to generate missing translations at scale.
 - Use `npx intlayer content test` to gate PRs on missing translations.
 - For verbose diagnostics, set `log.mode = 'verbose'`.
+- Use `intlayer` instead of `intlayerPlugin` and `intlayerMiddleware` instead of `intlayerMiddlewarePlugin` in your Vite configuration.
 
 ---
 
@@ -288,6 +289,12 @@ To work around this, we dropped the `intlayer watch` command, using the `--with`
 
 ---
 
+## Migration notes from v6 to v7
+
+Check the [migration notes from v6 to v7](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/releases/v7.md) for more information.
+
+---
+
 ## Useful links
 
 - [CLI reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md)