@intlayer/docs 7.3.15 → 7.5.0-canary.0

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-10-05
+updatedAt: 2025-12-13
 title: مكون مزامنة JSON
 description: مزامنة قواميس Intlayer مع ملفات JSON الخاصة بالتدويل من طرف ثالث (i18next، next-intl، react-intl، vue-i18n، والمزيد). احتفظ بنظام التدويل الحالي لديك أثناء استخدام Intlayer لإدارة وترجمة واختبار رسائلك.
 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: إضافة دعم تنسيقات ICU و i18next
   - version: 6.1.6
     date: 2025-10-05
     changes: الوثائق الأولية لمكون مزامنة JSON
 ---
 
-## مزامنة JSON (جسور التدويل)
+# مزامنة JSON (جسور التدويل) - مزامنة JSON مع دعم ICU / i18next
 
 <iframe title="كيفية الحفاظ على مزامنة ترجمات JSON الخاصة بك مع 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, // مطلوب
   location?: string, // تسمية اختيارية، الافتراضي: "plugin"
   priority?: number, // أولوية اختيارية لحل التعارضات، الافتراضي: 0
+  format?: 'intlayer' | 'icu' | 'i18next', // مُنسق اختياري، الافتراضي: 'intlayer'
 });
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+يحدد المُنسق الذي سيتم استخدامه لمحتوى القاموس عند مزامنة ملفات JSON. يسمح هذا باستخدام صيغ تنسيق رسائل مختلفة متوافقة مع مكتبات i18n مختلفة.
+
+- `'intlayer'`: مُنسق Intlayer الافتراضي (الافتراضي).
+- `'icu'`: يستخدم تنسيق رسائل ICU (متوافق مع مكتبات مثل react-intl، vue-i18n).
+- `'i18next'`: يستخدم تنسيق رسائل i18next (متوافق مع i18next، next-i18next، Solid-i18next).
+
+**مثال:**
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+  format: "i18next", // استخدام تنسيق i18next للتوافق
+}),
+```
+
 ## مصادر JSON متعددة والأولوية
 
 يمكنك إضافة عدة مكونات إضافية `syncJSON` لمزامنة مصادر JSON مختلفة. هذا مفيد عندما يكون لديك مكتبات i18n متعددة أو هياكل JSON مختلفة في مشروعك.
@@ -134,6 +155,7 @@ export default defineConfig({
   plugins: [
     // المصدر الأساسي لملفات JSON (الأولوية الأعلى)
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       location: "main-translations",
       priority: 10,
@@ -141,6 +163,7 @@ export default defineConfig({
 
     // المصدر الاحتياطي لملفات JSON (أولوية أقل)
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./fallback-locales/${locale}.json`,
       location: "fallback-translations",
       priority: 5,
@@ -148,6 +171,7 @@ export default defineConfig({
 
     // المصدر القديم لملفات JSON (الأولوية الأدنى)
     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/de/dictionary/content_file.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-02-07
-updatedAt: 2025-09-20
+updatedAt: 2025-12-13
 title: Inhaltsdatei
 description: Erfahren Sie, wie Sie die Erweiterungen für Ihre Inhaltsdeklarationsdateien anpassen können. Folgen Sie dieser Dokumentation, um Bedingungen effizient in Ihrem Projekt umzusetzen.
 keywords:
@@ -12,6 +12,9 @@ slugs:
   - concept
   - content
 history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: Unterstützung für ICU- und i18next-Formate hinzugefügt
   - version: 6.0.0
     date: 2025-09-20
     changes: Felddokumentation hinzugefügt
@@ -386,6 +389,26 @@ Array von Zeichenketten zur Kategorisierung und Organisation von Wörterbüchern
 }
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Gibt den Formatierer an, der für den Wörterbuchinhalt verwendet werden soll. Dies ermöglicht die Verwendung verschiedener Nachrichtenformatierungssyntaxen.
+
+- `'intlayer'`: Der Standard-Intlayer-Formatierer.
+- `'icu'`: Verwendet ICU-Nachrichtenformatierung.
+- `'i18next'`: Verwendet i18next-Nachrichtenformatierung.
+
+**Beispiel:**
+
+```typescript
+{
+  key: "my-dictionary",
+  format: "icu",
+  content: {
+    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"
+  }
+}
+```
+
 #### `locale` (LocalesValues)
 
 Wandelt das Wörterbuch in ein pro-Locale-Wörterbuch um, bei dem jedes im Inhalt deklarierte Feld automatisch in einen Übersetzungsknoten umgewandelt wird. Wenn diese Eigenschaft gesetzt ist:

package/docs/de/intlayer_with_astro.md

@@ -2,7 +2,7 @@
 createdAt: 2024-03-07
 updatedAt: 2025-10-03
 title: Wie Sie Ihre Astro übersetzen – i18n-Leitfaden 2025
-description: Erfahren Sie, wie Sie Internationalisierung (i18n) zu Ihrer Vite- und React-Anwendung mit Intlayer hinzufügen. Folgen Sie dieser Anleitung, um Ihre App mehrsprachig zu machen.
+description: Erfahren Sie, wie Sie Internationalisierung (i18n) zu Ihrer Astro-Website mit Intlayer hinzufügen. Folgen Sie dieser Anleitung, um Ihre Website mehrsprachig zu machen.
 keywords:
   - Internationalisierung
   - Dokumentation

package/docs/de/intlayer_with_express.md

@@ -2,7 +2,7 @@
 createdAt: 2024-08-11
 updatedAt: 2025-06-29
 title: Wie Sie Ihre Express backend übersetzen – i18n-Leitfaden 2025
-description: Entdecken Sie, wie Sie Ihre vite-Backend mehrsprachig gestalten können. Befolgen Sie die Dokumentation, um sie zu internationalisieren (i18n) und zu übersetzen.
+description: Entdecken Sie, wie Sie Ihre Express-Backend mehrsprachig gestalten können. Befolgen Sie die Dokumentation, um sie zu internationalisieren (i18n) und zu übersetzen.
 keywords:
   - Internationalisierung
   - Dokumentation

package/docs/de/intlayer_with_nestjs.md

@@ -2,7 +2,7 @@
 createdAt: 2025-09-09
 updatedAt: 2025-09-09
 title: Wie Sie Ihre Nest backend übersetzen – i18n-Leitfaden 2025
-description: Entdecken Sie, wie Sie Ihr Vite-Backend mehrsprachig machen. Folgen Sie der Dokumentation, um es zu internationalisieren (i18n) und zu übersetzen.
+description: Entdecken Sie, wie Sie Ihr NestJS-Backend mehrsprachig machen. Folgen Sie der Dokumentation, um es zu internationalisieren (i18n) und zu übersetzen.
 keywords:
   - Internationalisierung
   - Dokumentation

package/docs/de/intlayer_with_next-i18next.md

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

package/docs/de/intlayer_with_next-intl.md

@@ -419,6 +419,7 @@ const config: IntlayerConfig = {
   plugins: [
     // Synchronisieren Sie Ihre Ordnerstruktur pro Namespace mit Intlayer
     syncJSON({
+      format: "icu",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`, // Pfad zu den JSON-Übersetzungsdateien
     }),
   ],

package/docs/de/intlayer_with_tanstack.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2025-09-09
+updatedAt: 2025-12-11
 title: Wie Sie Ihre Tanstack Start übersetzen – i18n-Leitfaden 2025
 description: Erfahren Sie, wie Sie Internationalisierung (i18n) zu Ihrer Tanstack Start-Anwendung mit Intlayer hinzufügen. Folgen Sie dieser umfassenden Anleitung, um Ihre App mehrsprachig mit lokalisierungsbewusstem Routing zu machen.
 keywords:
@@ -19,9 +19,12 @@ 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: Füge validatePrefix hinzu und ergänze Schritt 14: 404-Seiten mit lokalisierten Routen behandeln.
   - version: 7.3.9
     date: 2025-12-05
-    changes: Add step 13: Retrieve the locale in your server actions (Optional)
+    changes: Füge Schritt 13 hinzu: Zugriff auf die aktuelle Locale in Serveraktionen (Optional)
   - version: 5.8.1
     date: 2025-09-09
     changes: Hinzugefügt für Tanstack Start
@@ -614,7 +617,123 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Schritt 14: TypeScript konfigurieren (optional)
+### Schritt 14: Nicht gefundene Seiten verwalten (optional)
+
+Wenn ein Benutzer eine nicht existierende Seite besucht, können Sie eine benutzerdefinierte Seite "Nicht gefunden" anzeigen, und das Locale-Präfix kann beeinflussen, wie die Seite "Nicht gefunden" ausgelöst wird.
+
+#### Verstehen der 404-Behandlung von TanStack Router mit Locale-Präfixen
+
+In TanStack Router erfordert die Behandlung von 404-Seiten mit lokalisierten Routen einen mehrschichtigen Ansatz:
+
+1. **Dedizierte 404-Route**: Eine spezifische Route zur Anzeige der 404-Benutzeroberfläche
+2. **Validierung auf Routenebene**: Validiert Locale-Präfixe und leitet ungültige zu 404 weiter
+3. **Catch-all-Route**: Erfasst alle nicht übereinstimmenden Pfade innerhalb des Locale-Segments
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// Dies erstellt eine dedizierte /[locale]/404 Route
+// Sie wird sowohl als direkte Route verwendet als auch als Komponente in anderen Dateien importiert
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// Separately exportiert, damit es in notFoundComponent und catch-all Routen wiederverwendet werden kann
+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 läuft, bevor die Route gerendert wird (sowohl auf Server als auch Client)
+  // Es ist der ideale Ort, um das Locale-Präfix zu validieren
+  beforeLoad: ({ params }) => {
+    // Locale aus Routenparametern abrufen (nicht aus Server-Headern, da beforeLoad sowohl auf Client als auch Server läuft)
+    const localeParam = params.locale;
+
+    // validatePrefix prüft, ob die Locale gemäß Ihrer intlayer-Konfiguration gültig ist
+    // Gibt zurück: { isValid: boolean, localePrefix: string }
+    // - isValid: true, wenn das Präfix mit einer konfigurierten Locale übereinstimmt (oder leer ist, wenn das Präfix optional ist)
+    // - localePrefix: das validierte Präfix oder das Standard-Locale-Präfix für Umleitungen
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // Locale ist gültig, Route normal rendern lassen
+      return;
+    }
+
+    // Ungültiges Locale-Präfix (z. B. /xyz/about, wobei "xyz" keine gültige Locale ist)
+    // Zur 404-Seite mit einem gültigen Locale-Präfix umleiten
+    // Dies stellt sicher, dass die 404-Seite weiterhin korrekt lokalisiert ist
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent wird aufgerufen, wenn eine untergeordnete Route nicht existiert
+  // z. B. löst /en/nicht-vorhandene-seite dies innerhalb des /en-Layouts aus
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // Den gesamten Locale-Segment mit IntlayerProvider umschließen
+    // Fällt auf defaultLocale zurück, wenn der locale-Parameter undefined ist (optionaler Präfix-Modus)
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout umschließt die 404-Komponente mit IntlayerProvider
+// Dies stellt sicher, dass Übersetzungen auf der 404-Seite weiterhin funktionieren
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* LocaleSwitcher einbinden, damit Benutzer die Sprache auch auf 404 ändern können */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// Die $ (splat/catch-all) Route passt auf jeden Pfad, der nicht mit anderen Routen übereinstimmt
+// z. B. /en/irgendein/tief/verschachtelter/ungültiger/pfad
+// Dies stellt sicher, dass ALLE nicht übereinstimmenden Pfade innerhalb einer Locale die 404-Seite anzeigen
+// Ohne dies könnten nicht übereinstimmende tiefe Pfade eine leere Seite oder einen Fehler anzeigen
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### Schritt 15: TypeScript konfigurieren (optional)
 
 Intlayer verwendet Module Augmentation, um die Vorteile von TypeScript zu nutzen und Ihren Code robuster zu machen.
 

package/docs/de/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: Synchronisieren Sie Intlayer-Wörterbücher mit Drittanbieter-i18n-JSON-Dateien (i18next, next-intl, react-intl, vue-i18n und mehr). Behalten Sie Ihr bestehendes i18n bei und verwenden Sie Intlayer, um Ihre Nachrichten zu verwalten, zu übersetzen und zu testen.
 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: Unterstützung für ICU- und i18next-Formate hinzugefügt
   - version: 6.1.6
     date: 2025-10-05
     changes: Erste Dokumentation des Sync JSON Plugins
 ---
 
-# Sync JSON (i18n-Brücken)
+# Sync JSON (i18n-Brücken) - Sync JSON mit ICU / i18next-Unterstützung
 
 <iframe title="Wie Sie Ihre JSON-Übersetzungen mit Intlayer synchronisiert halten" 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, // erforderlich
   location?: string, // optionales Label, Standard: "plugin"
   priority?: number, // optionale Priorität zur Konfliktlösung, Standard: 0
+  format?: 'intlayer' | 'icu' | 'i18next', // optionaler Formatierer, Standard: 'intlayer'
 });
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Gibt den Formatierer an, der für den Wörterbuchinhalt bei der Synchronisierung von JSON-Dateien verwendet werden soll. Dies ermöglicht die Verwendung verschiedener Nachrichtenformatierungssyntaxen, die mit verschiedenen i18n-Bibliotheken kompatibel sind.
+
+- `'intlayer'`: Der Standard-Intlayer-Formatierer (Standard).
+- `'icu'`: Verwendet ICU-Nachrichtenformatierung (kompatibel mit Bibliotheken wie react-intl, vue-i18n).
+- `'i18next'`: Verwendet i18next-Nachrichtenformatierung (kompatibel mit i18next, next-i18next, Solid-i18next).
+
+**Beispiel:**
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+  format: "i18next", // i18next-Formatierung für Kompatibilität verwenden
+}),
+```
+
 ## Mehrere JSON-Quellen und Priorität
 
 Sie können mehrere `syncJSON`-Plugins hinzufügen, um verschiedene JSON-Quellen zu synchronisieren. Dies ist nützlich, wenn Sie mehrere i18n-Bibliotheken oder unterschiedliche JSON-Strukturen in Ihrem Projekt haben.
@@ -134,6 +155,7 @@ export default defineConfig({
   plugins: [
     // Primäre JSON-Quelle (höchste Priorität)
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       location: "main-translations",
       priority: 10,
@@ -141,6 +163,7 @@ export default defineConfig({
 
     // Fallback-JSON-Quelle (niedrigere Priorität)
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./fallback-locales/${locale}.json`,
       location: "fallback-translations",
       priority: 5,
@@ -148,6 +171,7 @@ export default defineConfig({
 
     // Legacy-JSON-Quelle (niedrigste Priorität)
     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/en/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 customize 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: 7.0.0
     date: 2025-10-23
     changes: Rename `autoFill` to `fill`
@@ -387,6 +390,26 @@ Array of strings for categorizing and organizing 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/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 internationalization (i18n) to your Vite and React application using Intlayer. Follow this guide to make your app multilingual.
+description: Learn how to add internationalization (i18n) to your Astro website using Intlayer. Follow this guide to make your site multilingual.
 keywords:
   - Internationalization
   - Documentation

package/docs/en/intlayer_with_express.md

@@ -2,7 +2,7 @@
 createdAt: 2025-08-23
 updatedAt: 2025-08-23
 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/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 internationalize (i18n) and translate it.
+description: Discover how to make your NestJS backend multilingual. Follow the documentation to internationalize (i18n) and translate it.
 keywords:
   - Internationalization
   - Documentation
@@ -15,7 +15,6 @@ slugs:
   - environment
   - nest
 applicationTemplate: https://github.com/AydinTheFirst/nestjs-intlayer
-author: AydinTheFirst
 history:
   - version: 5.8.0
     date: 2025-09-09

package/docs/en/intlayer_with_next-i18next.md

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

package/docs/en/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/intlayer_with_tanstack.md

@@ -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)
@@ -611,7 +614,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 get benefits of TypeScript and make your codebase stronger.