@intlayer/docs 7.3.14 → 7.4.0

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

@@ -22,6 +22,7 @@ slugs:
   - doc
   - plugin
   - sync-json
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
   - version: 6.1.6
     date: 2025-10-05
@@ -30,6 +31,8 @@ history:
 
 ## सिंक JSON (i18n ब्रिजेस)
 
+<iframe title="Intlayer के साथ अपने JSON अनुवादों को सिंक में कैसे रखें" 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"/>
+
 अपने मौजूदा i18n स्टैक में एक ऐड-ऑन के रूप में Intlayer का उपयोग करें। यह प्लगइन आपके JSON संदेशों को Intlayer शब्दकोशों के साथ सिंक्रनाइज़ रखता है ताकि आप:
 
 - i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n आदि को बनाए रख सकें।

package/docs/id/intlayer_with_tanstack.md

@@ -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: Memperkenalkan validatePrefix dan menambah langkah 14: Menangani halaman 404 dengan rute terlokalisasi.
   - version: 7.3.9
     date: 2025-12-05
-    changes: Add step 13: Retrieve the locale in your server actions (Optional)
+    changes: Menambah langkah 13: Mengambil locale di server actions Anda (Opsional)
   - version: 6.5.2
     date: 2025-10-03
     changes: Memperbarui dokumen
@@ -592,7 +595,134 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Langkah 14: Konfigurasi TypeScript (Opsional)
+### Langkah 14: Mengelola halaman tidak ditemukan (Opsional)
+
+Ketika pengguna mengunjungi halaman yang tidak ada, Anda dapat menampilkan halaman tidak ditemukan yang disesuaikan dan awalan locale dapat mempengaruhi cara halaman tidak ditemukan dipicu.
+
+#### Memahami Penanganan 404 TanStack Router dengan Awalan Locale
+
+Di TanStack Router, menangani halaman 404 dengan rute yang dilokalisasi memerlukan pendekatan berlapis:
+
+1. **Rute 404 khusus**: Rute spesifik untuk menampilkan UI 404
+2. **Validasi tingkat rute**: Memvalidasi awalan locale dan mengarahkan ulang yang tidak valid ke 404
+3. **Rute catch-all**: Menangkap semua jalur yang tidak cocok dalam segmen locale
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// Ini membuat rute khusus /[locale]/404
+// Digunakan baik sebagai rute langsung maupun diimpor sebagai komponen di file lain
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// Diekspor secara terpisah agar dapat digunakan kembali di notFoundComponent dan rute catch-all
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/__root.tsx"
+import { createRootRoute } from "@tanstack/react-router";
+
+// Rute root berfungsi sebagai tata letak tingkat atas
+// Tidak menangani 404 secara langsung - itu didelegasikan ke rute anak
+// Ini menjaga root tetap sederhana dan memungkinkan rute yang sadar locale mengelola logika 404 mereka sendiri
+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";
+import { IntlayerProvider, useLocale } from "react-intlayer";
+
+import { LocaleSwitcher } from "@/components/locale-switcher";
+import { NotFoundComponent } from "./404";
+
+export const Route = createFileRoute("/{-$locale}")({
+  // beforeLoad berjalan sebelum rute dirender (baik di server maupun klien)
+  // Ini adalah tempat ideal untuk memvalidasi awalan locale
+  beforeLoad: ({ params }) => {
+    // Dapatkan locale dari parameter rute (bukan dari header server, karena beforeLoad berjalan di klien dan server)
+    const localeParam = params.locale;
+
+    // validatePrefix memeriksa apakah locale valid menurut konfigurasi intlayer Anda
+    // Mengembalikan: { isValid: boolean, localePrefix: string }
+    // - isValid: true jika awalan cocok dengan locale yang dikonfigurasi (atau kosong ketika awalan opsional)
+    // - localePrefix: awalan yang divalidasi atau awalan locale default untuk pengalihan
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // Locale valid, izinkan rute untuk dirender secara normal
+      return;
+    }
+
+    // Awalan locale tidak valid (misalnya, /xyz/about di mana "xyz" bukan locale yang valid)
+    // Alihkan ke halaman 404 dengan awalan locale yang valid
+    // Ini memastikan halaman 404 masih dilokalkan dengan benar
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent dipanggil ketika rute anak tidak ada
+  // misalnya, /en/halaman-tidak-ada memicu ini dalam tata letak /en
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // Bungkus seluruh segmen locale dengan IntlayerProvider
+    // Kembali ke defaultLocale ketika parameter locale adalah undefined (mode awalan opsional)
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout membungkus komponen 404 dengan IntlayerProvider
+// Ini memastikan terjemahan masih berfungsi di halaman 404
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* Sertakan LocaleSwitcher agar pengguna dapat mengubah bahasa bahkan di 404 */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// Rute $ (splat/catch-all) cocok dengan jalur apa pun yang tidak cocok dengan rute lain
+// misalnya, /en/beberapa/jalur/bersarang/mendalam/tidak-valid
+// Ini memastikan SEMUA jalur yang tidak cocok dalam locale menampilkan halaman 404
+// Tanpa ini, jalur dalam yang tidak cocok mungkin menampilkan halaman kosong atau kesalahan
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### Langkah 15: Konfigurasi TypeScript (Opsional)
 
 Intlayer menggunakan module augmentation untuk mendapatkan manfaat dari TypeScript dan membuat codebase Anda lebih kuat.
 

package/docs/id/intlayer_with_vite+react.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2024-03-07
+updatedAt: 2025-12-10
 title: Cara menerjemahkan aplikasi Vite dan React Anda – panduan i18n 2025
 description: Pelajari cara menambahkan internasionalisasi (i18n) ke aplikasi Vite dan React Anda menggunakan Intlayer. Ikuti panduan ini untuk membuat aplikasi Anda multibahasa.
 keywords:
@@ -85,10 +85,7 @@ yarn add vite-intlayer --save-dev
 ```
 
 - **intlayer**
-
-- **intlayer**
-
-  Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, [deklarasi konten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md), transpile, dan [perintah CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_cli.md).
+  Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, [deklarasi konten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md), transpile, dan [perintah CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/index.md).
 
 - **react-intlayer**
   Paket yang mengintegrasikan Intlayer dengan aplikasi React. Paket ini menyediakan context providers dan hooks untuk internasionalisasi React.
@@ -1212,7 +1209,7 @@ Dengan menerapkan perubahan ini, aplikasi Anda akan:
 
 ### (Opsional) Langkah 10: Membuat Komponen Link yang Dilokalkan
 
-Untuk memastikan navigasi aplikasi Anda menghormati locale saat ini, Anda dapat membuat komponen `Link` kustom. Komponen ini secara otomatis menambahkan prefix bahasa saat ini pada URL internal, sehingga. Misalnya, ketika pengguna berbahasa Prancis mengklik tautan ke halaman "About", mereka akan diarahkan ke `/fr/about` bukan `/about`.
+Untuk memastikan navigasi aplikasi Anda menghormati locale saat ini, Anda dapat membuat komponen `Link` kustom. Komponen ini secara otomatis menambahkan prefix bahasa saat ini pada URL internal, sehingga, misalnya, ketika pengguna berbahasa Prancis mengklik tautan ke halaman "About", mereka akan diarahkan ke `/fr/about` bukan `/about`.
 
 Perilaku ini berguna untuk beberapa alasan:
 
@@ -1231,11 +1228,10 @@ import {
 } from "react";
 import { useLocale } from "react-intlayer";
 
-export interface LinkProps
-  extends DetailedHTMLProps<
-    AnchorHTMLAttributes<HTMLAnchorElement>,
-    HTMLAnchorElement
-  > {}
+export interface LinkProps extends DetailedHTMLProps<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  HTMLAnchorElement
+> {}
 
 /**
  * Fungsi utilitas untuk memeriksa apakah URL yang diberikan bersifat eksternal.
@@ -1409,5 +1405,3 @@ Untuk detail lebih lanjut tentang cara menggunakan ekstensi ini, lihat [dokument
 ### Melangkah Lebih Jauh
 
 Untuk melangkah lebih jauh, Anda dapat mengimplementasikan [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_visual_editor.md) atau mengeksternalisasi konten Anda menggunakan [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_CMS.md).
-
----

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

@@ -22,6 +22,7 @@ slugs:
   - doc
   - plugin
   - sync-json
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
   - version: 6.1.6
     date: 2025-10-05
@@ -30,6 +31,8 @@ history:
 
 # Sinkronisasi JSON (jembatan i18n)
 
+<iframe title="Cara menjaga terjemahan JSON Anda tetap sinkron dengan 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"/>
+
 Gunakan Intlayer sebagai tambahan pada tumpukan i18n Anda yang sudah ada. Plugin ini menjaga pesan JSON Anda tetap sinkron dengan kamus Intlayer sehingga Anda dapat:
 
 - Mempertahankan i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n, dll.

package/docs/it/intlayer_with_lynx+react.md

@@ -428,7 +428,7 @@ Per cambiare la lingua direttamente dai tuoi componenti, puoi usare il metodo `s
 ```tsx fileName="src/components/LocaleSwitcher.tsx"
 import { type FC } from "react";
 import { getLocaleName } from "intlayer";
-import { useLocale } from "intlayer";
+import { useLocale } from "react-intlayer";
 
 export const LocaleSwitcher: FC = () => {
   const { setLocale, availableLocales, locale } = useLocale();

package/docs/it/intlayer_with_tanstack.md

@@ -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: Introdotto validatePrefix e aggiunto il passaggio 14: Gestione delle pagine 404 con rotte localizzate.
   - version: 7.3.9
     date: 2025-12-05
-    changes: Add step 13: Retrieve the locale in your server actions (Optional)
+    changes: Aggiunto passaggio 13: Recupera la lingua locale nelle server actions (Opzionale)
   - version: 6.5.2
     date: 2025-10-03
     changes: Aggiornamento documentazione
@@ -622,7 +625,134 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Passo 14: Configurare TypeScript (Opzionale)
+### Passo 14: Gestire le pagine non trovate (Opzionale)
+
+Quando un utente visita una pagina inesistente, puoi visualizzare una pagina personalizzata di non trovata e il prefisso locale può influenzare il modo in cui viene attivata la pagina di non trovata.
+
+#### Comprendere la gestione 404 di TanStack Router con prefissi locale
+
+In TanStack Router, gestire le pagine 404 con route localizzate richiede un approccio multistrato:
+
+1. **Route 404 dedicata**: Una route specifica per visualizzare l'interfaccia utente 404
+2. **Validazione a livello di route**: Valida i prefissi locale e reindirizza quelli non validi a 404
+3. **Route catch-all**: Cattura tutti i percorsi non corrispondenti all'interno del segmento locale
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// Questo crea una route dedicata /[locale]/404
+// Viene utilizzata sia come route diretta che importata come componente in altri file
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// Esportato separatamente in modo che possa essere riutilizzato in notFoundComponent e route catch-all
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/__root.tsx"
+import { createRootRoute } from "@tanstack/react-router";
+
+// La route radice funge da layout di livello superiore
+// Non gestisce i 404 direttamente - questo è delegato alle route figlie
+// Questo mantiene la radice semplice e consente alle route consapevoli della locale di gestire la propria logica 404
+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";
+import { IntlayerProvider, useLocale } from "react-intlayer";
+
+import { LocaleSwitcher } from "@/components/locale-switcher";
+import { NotFoundComponent } from "./404";
+
+export const Route = createFileRoute("/{-$locale}")({
+  // beforeLoad viene eseguito prima che la route venga renderizzata (sia sul server che sul client)
+  // È il posto ideale per validare il prefisso della locale
+  beforeLoad: ({ params }) => {
+    // Ottieni la locale dai parametri della route (non dagli header del server, poiché beforeLoad viene eseguito sia sul client che sul server)
+    const localeParam = params.locale;
+
+    // validatePrefix verifica se la locale è valida secondo la tua configurazione intlayer
+    // Restituisce: { isValid: boolean, localePrefix: string }
+    // - isValid: true se il prefisso corrisponde a una locale configurata (o è vuoto quando il prefisso è opzionale)
+    // - localePrefix: il prefisso validato o il prefisso della locale predefinito per i reindirizzamenti
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // La locale è valida, consenti alla route di renderizzarsi normalmente
+      return;
+    }
+
+    // Prefisso della locale non valido (ad esempio, /xyz/about dove "xyz" non è una locale valida)
+    // Reindirizza alla pagina 404 con un prefisso della locale valido
+    // Questo assicura che la pagina 404 sia ancora correttamente localizzata
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent viene chiamato quando una route figlia non esiste
+  // ad esempio, /en/pagina-inesistente attiva questo all'interno del layout /en
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // Avvolgi l'intero segmento della locale con IntlayerProvider
+    // Torna a defaultLocale quando il parametro locale è undefined (modalità prefisso opzionale)
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout avvolge il componente 404 con IntlayerProvider
+// Questo assicura che le traduzioni funzionino ancora sulla pagina 404
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* Includi LocaleSwitcher in modo che gli utenti possano cambiare lingua anche su 404 */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// La route $ (splat/catch-all) corrisponde a qualsiasi percorso che non corrisponde ad altre route
+// ad esempio, /en/qualche/percorso/profondamente/annidato/non-valido
+// Questo assicura che TUTTI i percorsi non corrispondenti all'interno di una locale mostrino la pagina 404
+// Senza questo, i percorsi profondi non corrispondenti potrebbero mostrare una pagina vuota o un errore
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### Passo 15: Configurare TypeScript (Opzionale)
 
 Intlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.