@intlayer/docs 7.3.15 → 7.5.0-canary.0

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/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:
@@ -19,6 +19,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-template
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 7.4.0
+    date: 2025-12-11
+    changes: Introduce validatePrefix and add step 14: Handling 404 pages with localized routes.
   - version: 7.3.9
     date: 2025-12-05
     changes: Add step 13: Retrieve the locale in your server actions (Optional)
@@ -602,7 +605,123 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Step 14: Configure TypeScript (Optional)
+### Step 14: Manage not found pages (Optional)
+
+When a user visits a non-existing page, you can display a custom not found page and the locale prefix may impact the way the not found page is triggered.
+
+#### Understanding TanStack Router's 404 Handling with Locale Prefixes
+
+In TanStack Router, handling 404 pages with localized routes requires a multi-layered approach:
+
+1. **Dedicated 404 route**: A specific route to display the 404 UI
+2. **Route-level validation**: Validates locale prefixes and redirects invalid ones to 404
+3. **Catch-all route**: Captures any unmatched paths within the locale segment
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// This creates a dedicated /[locale]/404 route
+// It's used both as a direct route and imported as a component in other files
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// Exported separately so it can be reused in notFoundComponent and catch-all routes
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/route.tsx"
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import { validatePrefix } from "intlayer";
+import { IntlayerProvider, useLocale } from "react-intlayer";
+
+import { LocaleSwitcher } from "@/components/locale-switcher";
+import { NotFoundComponent } from "./404";
+
+export const Route = createFileRoute("/{-$locale}")({
+  // beforeLoad runs before the route renders (on both server and client)
+  // It's the ideal place to validate the locale prefix
+  beforeLoad: ({ params }) => {
+    // Get locale from route params (not from server headers, as beforeLoad runs on both client and server)
+    const localeParam = params.locale;
+
+    // validatePrefix checks if the locale is valid according to your intlayer config
+    // Returns: { isValid: boolean, localePrefix: string }
+    // - isValid: true if the prefix matches a configured locale (or is empty when prefix is optional)
+    // - localePrefix: the validated prefix or the default locale prefix for redirects
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // Locale is valid, allow the route to render normally
+      return;
+    }
+
+    // Invalid locale prefix (e.g., /xyz/about where "xyz" isn't a valid locale)
+    // Redirect to the 404 page with a valid locale prefix
+    // This ensures the 404 page is still properly localized
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent is called when a child route doesn't exist
+  // e.g., /en/non-existent-page triggers this within the /en layout
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // Wrap the entire locale segment with IntlayerProvider
+    // Falls back to defaultLocale when locale param is undefined (optional prefix mode)
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout wraps the 404 component with IntlayerProvider
+// This ensures translations still work on the 404 page
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* Include LocaleSwitcher so users can change language even on 404 */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// The $ (splat/catch-all) route matches any path that doesn't match other routes
+// e.g., /en/some/deeply/nested/invalid/path
+// This ensures ALL unmatched paths within a locale show the 404 page
+// Without this, unmatched deep paths might show a blank page or error
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### Step 15: Configure TypeScript (Optional)
 
 Intlayer uses module augmentation to benefit from TypeScript and strengthen your codebase.
 

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/dictionary/content_file.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-02-07
-updatedAt: 2025-09-20
+updatedAt: 2025-12-13
 title: Archivo de Contenido
 description: Aprende a personalizar las extensiones para tus archivos de declaración de contenido. Sigue esta documentación para implementar condiciones de manera eficiente en tu proyecto.
 keywords:
@@ -12,6 +12,9 @@ slugs:
   - concept
   - content
 history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: Añadido soporte para formatos ICU e i18next
   - version: 6.0.0
     date: 2025-09-20
     changes: Añadida documentación de campos
@@ -385,6 +388,26 @@ Array de cadenas para categorizar y organizar diccionarios. Las etiquetas propor
 }
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Especifica el formateador a utilizar para el contenido del diccionario. Esto permite usar diferentes sintaxis de formateo de mensajes.
+
+- `'intlayer'`: El formateador Intlayer por defecto.
+- `'icu'`: Usa el formateo de mensajes ICU.
+- `'i18next'`: Usa el formateo de mensajes i18next.
+
+**Ejemplo:**
+
+```typescript
+{
+  key: "my-dictionary",
+  format: "icu",
+  content: {
+    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"
+  }
+}
+```
+
 #### `locale` (LocalesValues)
 
 Transforma el diccionario en un diccionario por localización donde cada campo declarado en el contenido se transformará automáticamente en un nodo de traducción. Cuando esta propiedad está establecida:

package/docs/es/intlayer_with_astro.md

@@ -2,7 +2,7 @@
 createdAt: 2024-03-07
 updatedAt: 2025-10-03
 title: Cómo traducir tu Astro – guía i18n 2025
-description: Aprende cómo agregar internacionalización (i18n) a tu aplicación Vite y React usando Intlayer. Sigue esta guía para hacer tu aplicación multilingüe.
+description: Aprende cómo agregar internacionalización (i18n) a tu sitio web Astro usando Intlayer. Sigue esta guía para hacer tu sitio multilingüe.
 keywords:
   - Internacionalización
   - Documentación

package/docs/es/intlayer_with_express.md

@@ -2,7 +2,7 @@
 createdAt: 2024-08-11
 updatedAt: 2025-06-29
 title: Cómo traducir tu Express backend – guía i18n 2025
-description: Descubre cómo hacer que tu backend de vite sea multilingüe. Sigue la documentación para internacionalizar (i18n) y traducirlo.
+description: Descubre cómo hacer que tu backend de Express sea multilingüe. Sigue la documentación para internacionalizar (i18n) y traducirlo.
 keywords:
   - Internacionalización
   - Documentación

package/docs/es/intlayer_with_nestjs.md

@@ -2,7 +2,7 @@
 createdAt: 2025-09-09
 updatedAt: 2025-09-09
 title: Cómo traducir tu Nest backend – guía i18n 2025
-description: Descubre cómo hacer que tu backend vite sea multilingüe. Sigue la documentación para internacionalizar (i18n) y traducirlo.
+description: Descubre cómo hacer que tu backend NestJS sea multilingüe. Sigue la documentación para internacionalizar (i18n) y traducirlo.
 keywords:
   - Internacionalización
   - Documentación

package/docs/es/intlayer_with_next-i18next.md

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

package/docs/es/intlayer_with_next-intl.md

@@ -419,6 +419,7 @@ const config: IntlayerConfig = {
   plugins: [
     // Mantén la estructura de carpetas por namespace sincronizada con Intlayer
     syncJSON({
+      format: "icu",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
     }),
   ],