@intlayer/docs 7.4.0 → 7.5.0-canary.1

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-10-05
+updatedAt: 2025-12-13
 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,12 +24,15 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: Add ICU and i18next format support
   - version: 6.1.6
     date: 2025-10-05
     changes: Initial Sync JSON plugin documentation
 ---
 
-# Sync JSON (i18n bridges)
+# Sync JSON (i18n bridges) - Sync JSON with ICU / i18next support
 
 <iframe title="How to keep your JSON translations in sync with Intlayer" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
 
@@ -95,13 +98,16 @@ const config: IntlayerConfig = {
       source: ({ key }) => `./src/**/${key}.i18n.json`,
       locale: Locales.ENGLISH,
       priority: 1, // Ensures these JSON files take precedence over files at `./locales/en/${key}.json`
+      format: "intlayer", // Format of the JSON content
     }),
     /**
      * Will load, and write the output and translations back to the JSON files in the locales directory
      */
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
+      format: "i18next",
     }),
   ],
 };
@@ -130,6 +136,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Per-locale, per-namespace layout (e.g., next-intl, i18next with namespaces)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -150,7 +157,9 @@ const config: IntlayerConfig = {
   },
   plugins: [
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
     }),
   ],
 };
@@ -171,9 +180,27 @@ syncJSON({
   source: ({ key, locale }) => string, // required
   location?: string, // optional label, default: "plugin"
   priority?: number, // optional priority for conflict resolution, default: 0
+  format?: 'intlayer' | 'icu' | 'i18next', // optional formatter, default: 'intlayer'
 });
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Specifies the formatter to use for the dictionary content when synchronizing JSON files. This allows using different message formatting syntaxes compatible with various i18n libraries.
+
+- `'intlayer'`: The default Intlayer formatter (default).
+- `'icu'`: Uses ICU message formatting (compatible with libraries like react-intl, vue-i18n).
+- `'i18next'`: Uses i18next message formatting (compatible with i18next, next-i18next, Solid-i18next).
+
+**Example:**
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+  format: "i18next", // Use i18next formatting for compatibility
+}),
+```
+
 ### 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.
@@ -200,6 +227,7 @@ const config: IntlayerConfig = {
   plugins: [
     // Primary JSON source (highest priority)
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       location: "main-translations",
       priority: 10,
@@ -207,6 +235,7 @@ const config: IntlayerConfig = {
 
     // Fallback JSON source (lower priority)
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./fallback-locales/${locale}.json`,
       location: "fallback-translations",
       priority: 5,
@@ -214,6 +243,7 @@ const config: IntlayerConfig = {
 
     // Legacy JSON source (lowest priority)
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
       location: "legacy-translations",
       priority: 1,
@@ -300,9 +330,30 @@ loadJSON({
 
   // Priority used for conflict resolution against other sources
   priority?: number, // default: 0
+
+  // Optional formatter for the JSON content
+  format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
 });
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Specifies the formatter to use for the dictionary content when loading JSON files. This allows using different message formatting syntaxes compatible with various i18n libraries.
+
+- `'intlayer'`: The default Intlayer formatter (default).
+- `'icu'`: Uses ICU message formatting (compatible with libraries like react-intl, vue-i18n).
+- `'i18next'`: Uses i18next message formatting (compatible with i18next, next-i18next, Solid-i18next).
+
+**Example:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Use ICU formatting for compatibility
+}),
+```
+
 ### Behavior and conventions
 
 - If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.

package/docs/en-GB/cli/index.md

@@ -103,6 +103,10 @@ To see how to configure available locales, or other parameters, refer to the [co
 
 ## Run intlayer commands
 
+### Authentication
+
+- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/login.md)** - Authenticate with the Intlayer CMS and get access credentials
+
 ### Core Commands
 
 - **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/build.md)** - Build your dictionaries from content declaration files
@@ -144,6 +148,7 @@ To see how to configure available locales, or other parameters, refer to the [co
 
 ```json fileName="package.json"
 "scripts": {
+  "intlayer:login": "npx intlayer login",
   "intlayer:build": "npx intlayer build",
   "intlayer:watch": "npx intlayer build --watch",
   "intlayer:push": "npx intlayer push",

package/docs/en-GB/cli/login.md

@@ -0,0 +1,181 @@
+---
+createdAt: 2025-12-16
+updatedAt: 2025-12-16
+title: CLI - Login
+description: Learn how to use the Intlayer CLI login command to authenticate with the Intlayer CMS and obtain access credentials.
+keywords:
+  - CLI
+  - Login
+  - Authentication
+  - CMS
+  - Intlayer
+  - Credentials
+slugs:
+  - doc
+  - concept
+  - cli
+  - login
+---
+
+# Intlayer CLI Login Command
+
+---
+
+## Description
+
+The `login` command of the Intlayer CLI allows you to authenticate with the Intlayer CMS. This command automatically opens your default browser to complete the authentication process and receive the necessary credentials (Client ID and Client Secret) to use Intlayer services.
+
+## Usage
+
+```bash
+npx intlayer login [options]
+```
+
+or
+
+```bash
+intlayer login [options]
+```
+
+## Options
+
+### `--cms-url <url>`
+
+Specify the URL of the Intlayer CMS to connect to for authentication.
+
+- **Type**: `string`
+- **Default**: The value configured in `intlayer.config.*` or `https://intlayer.org`
+- **Example**:
+
+```bash
+npx intlayer login --cms-url https://intlayer.org
+```
+
+### Configuration Options
+
+You can also use common configuration options:
+
+- `--env-file <path>`: Path to the environment file
+- `-e, --env <env>`: Execution environment
+- `--base-dir <dir>`: Base directory of the project
+- `--verbose`: Enable detailed output (default: true)
+- `--prefix <prefix>`: Prefix for logs
+
+## How It Works
+
+1. **Local server start**: The command starts a local HTTP server on a random port to receive credentials from the CMS
+
+Specify the URL of the Intlayer CMS to connect to for authentication.
+
+- **Type**: `string`
+- **Default**: The value configured in `intlayer.config.*` or `https://intlayer.org`
+- **Example**:
+
+```bash
+npx intlayer login --cms-url https://intlayer.org
+```
+
+### Configuration Options
+
+You can also use common configuration options:
+
+- `--env-file <path>`: Path to the environment file
+- `-e, --env <env>`: Execution environment
+- `--base-dir <dir>`: Base directory of the project
+- `--verbose`: Enable verbose output (default: true)
+- `--prefix <prefix>`: Prefix for logs
+
+## How It Works
+
+1. **Local Server Start**: The command starts a local HTTP server on a random port to receive credentials from the CMS.
+2. **Browser opening**: The command automatically opens your default browser to the CMS login URL
+3. **Authentication**: Complete the authentication in the browser using your Intlayer account
+4. **Credentials reception**: The local server receives the Client ID and Client Secret from the CMS
+5. **Instructions**: The command displays instructions for configuring credentials in your project
+
+## Output
+
+After a successful login, the command will display:
+
+1. **The received credentials** (Client ID and Client Secret)
+2. **Instructions for the `.env` file**:
+
+```bash
+INTLAYER_CLIENT_ID=your_client_id
+INTLAYER_CLIENT_SECRET=your_client_secret
+```
+
+3. **Instructions for the Intlayer configuration file**:
+
+```typescript
+{
+  editor: {
+    cmsURL: 'https://intlayer.org',
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+}
+```
+
+## Manual Configuration
+
+If the browser does not open automatically, you can manually visit the URL displayed in the terminal.
+
+## Examples
+
+### Login with Custom CMS URL
+
+```bash
+npx intlayer login --cms-url https://custom-cms.example.com
+```
+
+### Login with Specific Environment File
+
+```bash
+npx intlayer login --env-file .env.production
+```
+
+### Login in Verbose Mode
+
+```bash
+npx intlayer login --verbose
+```
+
+## Troubleshooting
+
+### Browser Doesn't Open
+
+If the browser does not open automatically, copy the URL displayed in the terminal and open it manually in your browser.
+
+### Connection Issues
+
+If you encounter connection issues, verify:
+
+1. That the CMS URL is correct
+2. That your internet connection is working correctly
+3. That no firewalls are blocking the connection
+
+### Credentials Not Received
+
+If credentials are not received:
+
+1. Ensure you have completed the authentication process in the browser
+2. Verify that the local port is not blocked
+3. Try the command again
+
+## Next Steps
+
+After completing the login:
+
+1. Add the credentials to your `.env` file
+2. Configure your `intlayer.config.*` file with the credentials
+3. Use CLI commands to manage your dictionaries:
+   - [`npx intlayer push`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/push.md) - Push dictionaries to the CMS
+   - [`npx intlayer pull`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/pull.md) - Pull dictionaries from the CMS
+   - [`npx intlayer fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/fill.md) - Fill in missing translations
+
+## See Also
+
+- [CLI Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/index.md)
+- [Intlayer Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+- [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)

package/docs/en-GB/configuration.md

@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 7.5.0
+    date: 2025-12-17
+    changes: Add `buildMode` option
   - version: 6.0.0
     date: 2025-09-16
     changes: Add `live` import mode
@@ -528,6 +531,15 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
 
 #### Properties
 
+- **mode**:
+  - _Type_: `'auto' | 'manual'`
+  - _Default_: `'auto'`
+  - _Description_: Controls the mode of the build.
+  - _Example_: `'manual'`
+  - _Note_: If 'auto', the build will be enabled automatically when the application is built.
+  - _Note_: If 'manual', the build will be set only when the build command is executed.
+  - _Note_: Can be used to disable dictionaries build, for instance when execution on Node.js environment should be avoided.
+
 - **optimize**:
   - _Type_: `boolean`
   - _Default_: `process.env.NODE_ENV === 'production'`

package/docs/en-GB/dictionary/content_file.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-02-07
-updatedAt: 2025-09-20
+updatedAt: 2025-12-13
 title: Content File
 description: Learn how to customise the extensions for your content declaration files. Follow this documentation to implement conditions efficiently in your project.
 keywords:
@@ -12,6 +12,9 @@ slugs:
   - concept
   - content
 history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: Add ICU and i18next format support
   - version: 6.0.0
     date: 2025-09-20
     changes: Add fields documentation
@@ -384,6 +387,26 @@ Array of strings for categorising and organising dictionaries. Tags provide addi
 }
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Specifies the formatter to use for the dictionary content. This allows using different message formatting syntaxes.
+
+- `'intlayer'`: The default Intlayer formatter.
+- `'icu'`: Uses ICU message formatting.
+- `'i18next'`: Uses i18next message formatting.
+
+**Example:**
+
+```typescript
+{
+  key: "my-dictionary",
+  format: "icu",
+  content: {
+    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"
+  }
+}
+```
+
 #### `locale` (LocalesValues)
 
 Transforms the dictionary into a per-locale dictionary where each field declared in the content will be automatically transformed into a translation node. When this property is set:

package/docs/en-GB/intlayer_with_astro.md

@@ -2,7 +2,7 @@
 createdAt: 2024-03-07
 updatedAt: 2025-10-03
 title: How to translate your Astro app – i18n guide 2025
-description: Learn how to add internationalisation (i18n) to your Vite and React application using Intlayer. Follow this guide to make your app multilingual.
+description: Learn how to add internationalisation (i18n) to your Astro website using Intlayer. Follow this guide to make your site multilingual.
 keywords:
   - Internationalisation
   - Documentation

package/docs/en-GB/intlayer_with_express.md

@@ -2,7 +2,7 @@
 createdAt: 2024-08-11
 updatedAt: 2025-06-29
 title: How to translate your Express backend – i18n guide 2025
-description: Discover how to make your vite backend multilingual. Follow the documentation to internationalize (i18n) and translate it.
+description: Discover how to make your Express backend multilingual. Follow the documentation to internationalize (i18n) and translate it.
 keywords:
   - Internationalization
   - Documentation

package/docs/en-GB/intlayer_with_nestjs.md

@@ -2,7 +2,7 @@
 createdAt: 2025-09-09
 updatedAt: 2025-09-09
 title: How to translate your Nest backend – i18n guide 2025
-description: Discover how to make your vite backend multilingual. Follow the documentation to internationalise (i18n) and translate it.
+description: Discover how to make your NestJS backend multilingual. Follow the documentation to internationalise (i18n) and translate it.
 keywords:
   - Internationalisation
   - Documentation

package/docs/en-GB/intlayer_with_next-i18next.md

@@ -580,6 +580,7 @@ const config: IntlayerConfig = {
   },
   plugins: [
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./locales/${locale}.json`,
     }),
   ],

package/docs/en-GB/intlayer_with_next-intl.md

@@ -419,6 +419,7 @@ const config: IntlayerConfig = {
   plugins: [
     // Keep your per-namespace folder structure in sync with Intlayer
     syncJSON({
+      format: "icu",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
     }),
   ],

package/docs/en-GB/intlayer_with_tanstack.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2025-09-09
+updatedAt: 2025-12-11
 title: How to translate your Tanstack Start app – i18n guide 2025
 description: Learn how to add internationalisation (i18n) to your Tanstack Start application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
 keywords:
@@ -636,17 +636,6 @@ export function NotFoundComponent() {
 }
 ```
 
-```tsx fileName="src/routes/__root.tsx"
-import { createRootRoute } from "@tanstack/react-router";
-
-// The root route serves as the top-level layout
-// It doesn't handle 404s directly - that's delegated to child routes
-// This keeps the root simple and lets locale-aware routes manage their own 404 logic
-export const Route = createRootRoute({
-  component: Outlet,
-});
-```
-
 ```tsx fileName="src/routes/{-$locale}/route.tsx"
 import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
 import { validatePrefix } from "intlayer";

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

@@ -24,12 +24,15 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: Add ICU and i18next format support
   - version: 6.1.6
     date: 2025-10-05
     changes: Initial Sync JSON plugin documentation
 ---
 
-## Sync JSON (i18n bridges)
+# Sync JSON (i18n bridges) - Sync JSON with ICU / i18next support
 
 <iframe title="How to keep your JSON translations in sync with Intlayer" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
 
@@ -105,9 +108,27 @@ syncJSON({
   source: ({ key, locale }) => string, // required
   location?: string, // optional label, default: "plugin"
   priority?: number, // optional priority for conflict resolution, default: 0
+  format?: 'intlayer' | 'icu' | 'i18next', // optional formatter, default: 'intlayer'
 });
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Specifies the formatter to use for the dictionary content when synchronising JSON files. This allows using different message formatting syntaxes compatible with various i18n libraries.
+
+- `'intlayer'`: The default Intlayer formatter (default).
+- `'icu'`: Uses ICU message formatting (compatible with libraries like react-intl, vue-i18n).
+- `'i18next'`: Uses i18next message formatting (compatible with i18next, next-i18next, Solid-i18next).
+
+**Example:**
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+  format: "i18next", // Use i18next formatting for compatibility
+}),
+```
+
 ## Multiple JSON sources and priority
 
 You can add multiple `syncJSON` plugins to synchronise different JSON sources. This is useful when you have multiple i18n libraries or different JSON structures in your project.
@@ -134,6 +155,7 @@ export default defineConfig({
   plugins: [
     // Primary JSON source (highest priority)
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       location: "main-translations",
       priority: 10,
@@ -141,6 +163,7 @@ export default defineConfig({
 
     // Fallback JSON source (lower priority)
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./fallback-locales/${locale}.json`,
       location: "fallback-translations",
       priority: 5,
@@ -148,6 +171,7 @@ export default defineConfig({
 
     // Legacy JSON source (lowest priority)
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
       location: "legacy-translations",
       priority: 1,
@@ -178,6 +202,7 @@ import { syncJSON } from "@intlayer/sync-json-plugin";
 export default {
   plugins: [
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
     }),
   ],

package/docs/es/cli/index.md

@@ -103,6 +103,10 @@ Para ver cómo configurar los locales disponibles u otros parámetros, consulta
 
 ## Ejecutar comandos de intlayer
 
+### Autenticación
+
+- **[Iniciar sesión](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/login.md)** - Autenticarse con el CMS de Intlayer y obtener credenciales de acceso
+
 ### Comandos principales
 
 - **[Construir Diccionarios](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/build.md)** - Construye tus diccionarios a partir de archivos de declaración de contenido
@@ -144,6 +148,7 @@ Para ver cómo configurar los locales disponibles u otros parámetros, consulta
 
 ```json fileName="package.json"
 "scripts": {
+  "intlayer:login": "npx intlayer login",
   "intlayer:build": "npx intlayer build",
   "intlayer:watch": "npx intlayer build --watch",
   "intlayer:push": "npx intlayer push",