@intlayer/docs 7.3.14 → 7.4.0

package/docs/pl/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: Wprowadzenie validatePrefix oraz dodanie kroku 14: Obsługa stron 404 z lokalizowanymi trasami.
   - version: 7.3.9
     date: 2025-12-05
-    changes: Add step 13: Retrieve the locale in your server actions (Optional)
+    changes: Dodany krok 13: Pobieranie lokalizacji w akcjach serwerowych (Opcjonalnie)
   - version: 6.5.2
     date: 2025-10-03
     changes: Aktualizacja dokumentacji
@@ -590,7 +593,134 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Krok 14: Konfiguracja TypeScript (opcjonalnie)
+### Krok 14: Zarządzanie stronami nie znalezionymi (opcjonalnie)
+
+Gdy użytkownik odwiedza nieistniejącą stronę, możesz wyświetlić niestandardową stronę "nie znaleziono", a prefiks locale może wpływać na sposób wyzwalania strony "nie znaleziono".
+
+#### Zrozumienie obsługi 404 w TanStack Router z prefiksami locale
+
+W TanStack Router obsługa stron 404 z zlokalizowanymi trasami wymaga podejścia wielowarstwowego:
+
+1. **Dedykowana trasa 404**: Konkretna trasa do wyświetlenia interfejsu 404
+2. **Walidacja na poziomie trasy**: Weryfikuje prefiksy locale i przekierowuje nieprawidłowe do 404
+3. **Trasa catch-all**: Przechwytuje wszystkie niedopasowane ścieżki w segmencie locale
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// To tworzy dedykowaną trasę /[locale]/404
+// Jest używana zarówno jako bezpośrednia trasa, jak i importowana jako komponent w innych plikach
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// Eksportowane osobno, aby można było ponownie użyć w notFoundComponent i trasach catch-all
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/__root.tsx"
+import { createRootRoute } from "@tanstack/react-router";
+
+// Trasa główna służy jako układ najwyższego poziomu
+// Nie obsługuje 404 bezpośrednio - to jest delegowane do tras potomnych
+// To utrzymuje główną trasę prostą i pozwala trasom świadomym locale zarządzać własną logiką 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 uruchamia się przed renderowaniem trasy (zarówno na serwerze, jak i kliencie)
+  // To idealne miejsce do walidacji prefiksu locale
+  beforeLoad: ({ params }) => {
+    // Pobierz locale z parametrów trasy (nie z nagłówków serwera, ponieważ beforeLoad działa zarówno na kliencie, jak i serwerze)
+    const localeParam = params.locale;
+
+    // validatePrefix sprawdza, czy locale jest prawidłowe zgodnie z konfiguracją intlayer
+    // Zwraca: { isValid: boolean, localePrefix: string }
+    // - isValid: true, jeśli prefiks pasuje do skonfigurowanego locale (lub jest pusty, gdy prefiks jest opcjonalny)
+    // - localePrefix: zwalidowany prefiks lub domyślny prefiks locale do przekierowań
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // Locale jest prawidłowe, pozwól trasie renderować się normalnie
+      return;
+    }
+
+    // Nieprawidłowy prefiks locale (np. /xyz/about, gdzie "xyz" nie jest prawidłowym locale)
+    // Przekieruj do strony 404 z prawidłowym prefiksem locale
+    // To zapewnia, że strona 404 jest nadal prawidłowo zlokalizowana
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent jest wywoływane, gdy trasa potomna nie istnieje
+  // np. /en/nieistniejaca-strona wyzwala to w układzie /en
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // Owiń cały segment locale w IntlayerProvider
+    // Powraca do defaultLocale, gdy parametr locale jest undefined (tryb opcjonalnego prefiksu)
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout owija komponent 404 w IntlayerProvider
+// To zapewnia, że tłumaczenia nadal działają na stronie 404
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* Dołącz LocaleSwitcher, aby użytkownicy mogli zmieniać język nawet na 404 */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// Trasa $ (splat/catch-all) pasuje do każdej ścieżki, która nie pasuje do innych tras
+// np. /en/jakas/gleboko/zagniezdzona/niewazna/sciezka
+// To zapewnia, że WSZYSTKIE niedopasowane ścieżki w locale wyświetlają stronę 404
+// Bez tego niedopasowane głębokie ścieżki mogą wyświetlać pustą stronę lub błąd
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### Krok 15: Konfiguracja TypeScript (opcjonalnie)
 
 Intlayer używa rozszerzenia modułów (module augmentation), aby wykorzystać zalety TypeScript i wzmocnić Twoją bazę kodu.
 

package/docs/pl/intlayer_with_vite+react.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2024-03-07
+updatedAt: 2025-12-10
 title: Jak przetłumaczyć swoją aplikację Vite i React – przewodnik i18n 2025
 description: Dowiedz się, jak dodać internacjonalizację (i18n) do swojej aplikacji Vite i React za pomocą Intlayer. Postępuj zgodnie z tym przewodnikiem, aby uczynić swoją aplikację wielojęzyczną.
 keywords:
@@ -85,10 +85,7 @@ yarn add vite-intlayer --save-dev
 ```
 
 - **intlayer**
-
-- **intlayer**
-
-  Podstawowy pakiet, który dostarcza narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczeń, [deklaracji treści](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md), transpilecji oraz [poleceń CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_cli.md).
+  Główny pakiet dostarczający narzędzia do internacjonalizacji dla zarządzania konfiguracją, tłumaczeń, [deklaracji treści](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md), transpilecji oraz [poleceń CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/index.md).
 
 - **react-intlayer**
   Pakiet integrujący Intlayer z aplikacją React. Zapewnia dostawców kontekstu oraz hooki do internacjonalizacji w React.
@@ -464,7 +461,7 @@ module.exports = appContent;
 }
 ```
 
-> Twoje deklaracje zawartości mogą być definiowane w dowolnym miejscu w aplikacji, pod warunkiem, że zostaną umieszczone w katalogu `contentDir` (domyślnie `./src`). I będą miały rozszerzenie pliku deklaracji zawartości (domyślnie `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+> Twoje deklaracje zawartości mogą być definiowane w dowolnym miejscu w aplikacji, pod warunkiem, że zostaną umieszczone w katalogu `contentDir` (domyślnie `./src`) i będą miały rozszerzenie pliku deklaracji zawartości (domyślnie `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
 
 > Aby uzyskać więcej szczegółów, zapoznaj się z [dokumentacją deklaracji zawartości](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md).
 
@@ -688,7 +685,7 @@ Przykład:
 
 > Domyślnie trasy nie mają prefiksu dla domyślnej lokalizacji. Jeśli chcesz dodać prefiks dla domyślnej lokalizacji, możesz ustawić opcję `middleware.prefixDefault` na `true` w swojej konfiguracji. Więcej informacji znajdziesz w [dokumentacji konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
 
-Aby dodać lokalizowane routingi do swojej aplikacji, możesz utworzyć komponent `LocaleRouter`, który opakuje trasy Twojej aplikacji i obsłuży routing oparty na lokalizacji. Oto przykład z użyciem [React Router](https://reactrouter.com/home):
+Aby dodać lokalizowany routing do swojej aplikacji, możesz utworzyć komponent `LocaleRouter`, który opakuje trasy Twojej aplikacji i obsłuży routing oparty na lokalizacji. Oto przykład z użyciem [React Router](https://reactrouter.com/home):
 
 ```tsx fileName="src/components/LocaleRouter.tsx"  codeFormat="typescript"
 import { localeMap } from "intlayer"; // Funkcje narzędziowe i typy z 'intlayer'
@@ -709,6 +706,16 @@ export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
           path={`${urlPrefix}/*`}
           key={locale}
           element={
+            <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+          } // Opakowuje dzieci zarządzaniem lokalizacją
+        />
+      ))}
+    </Routes>
+  </BrowserRouter>
+);
+```
+
+```jsx fileName="src/components/LocaleRouter.mjx" codeFormat="esm"
 import { localeMap } from 'intlayer'; // Funkcje narzędziowe i typy z 'intlayer'
 import type { FC, PropsWithChildren } from 'react'; // Typy React dla komponentów funkcyjnych i propsów
 import { IntlayerProvider } from 'react-intlayer'; // Provider dla kontekstu internacjonalizacji
@@ -716,7 +723,7 @@ import { BrowserRouter, Route, Routes } from 'react-router-dom'; // Komponenty r
 
 /**
  * Komponent routera, który ustawia trasy specyficzne dla lokalizacji.
- * Używa React Router do zarządzania nawigacją i renderowania lokalizowanych komponentów.
+ * Używa React Router do zarządzania nawigacją i renderowania zlokalizowanych komponentów.
  */
 export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
   <BrowserRouter>
@@ -728,7 +735,7 @@ export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
           key={locale}
           element={
             <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
-          } // Opakowuje dzieci zarządzaniem lokalizacją
+          } // Owinie dzieci w zarządzanie lokalizacją
         />
       ))}
     </Routes>
@@ -1049,8 +1056,8 @@ const LocaleSwitcher = () => {
 > - [`getHTMLTextDir` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getHTMLTextDir.md)
 > - [`hrefLang` attribute](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=fr)
 > - [`lang` attribute](https://developer.mozilla.org/pl/docs/Web/HTML/Global_attributes/lang)
-> - [`dir` attribute`](https://developer.mozilla.org/pl/docs/Web/HTML/Global_attributes/dir)
-> - [`aria-current` attribute`](https://developer.mozilla.org/pl/docs/Web/Accessibility/ARIA/Attributes/aria-current)
+> - [`dir` attribute](https://developer.mozilla.org/pl/docs/Web/HTML/Global_attributes/dir)
+> - [`aria-current` attribute](https://developer.mozilla.org/pl/docs/Web/Accessibility/ARIA/Attributes/aria-current)
 
 Poniżej znajduje się zaktualizowany **Krok 9** z dodatkowymi wyjaśnieniami i dopracowanymi przykładami kodu:
 
@@ -1231,9 +1238,9 @@ module.exports = App;
 
 Wprowadzając te zmiany, twoja aplikacja:
 
-- Zapewni, że atrybut **language** (`lang`) poprawnie odzwierciedla aktualną lokalizację, co jest ważne dla SEO i zachowania przeglądarki.
-- Dostosuje **kierunek tekstu** (`dir`) zgodnie z lokalizacją, poprawiając czytelność i użyteczność dla języków o różnych kierunkach czytania.
-- Zapewni bardziej **dostępne** doświadczenie, ponieważ technologie wspomagające polegają na tych atrybutach, aby działać optymalnie.
+- Upewnij się, że atrybut **language** (`lang`) poprawnie odzwierciedla aktualną lokalizację, co jest ważne dla SEO i zachowania przeglądarki.
+- Dostosuj **kierunek tekstu** (`dir`) zgodnie z lokalizacją, poprawiając czytelność i użyteczność dla języków o różnych kierunkach czytania.
+- Zapewnij bardziej **dostępne** doświadczenie, ponieważ technologie wspomagające polegają na tych atrybutach, aby działać optymalnie.
 
 ### (Opcjonalny) Krok 10: Tworzenie lokalizowanego komponentu Link
 
@@ -1256,11 +1263,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
+> {}
 
 /**
  * Funkcja pomocnicza do sprawdzania, czy dany URL jest zewnętrzny.
@@ -1434,5 +1440,3 @@ Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj si
 ### Idź dalej
 
 Aby pójść dalej, możesz zaimplementować [edytor wizualny](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_visual_editor.md) lub wyodrębnić swoją zawartość, korzystając z [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md).
-
----

package/docs/pl/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:
 
 # Sync JSON (mosty i18n)
 
+<iframe title="Jak zachować synchronizację tłumaczeń JSON z 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"/>
+
 Użyj Intlayer jako dodatku do istniejącego stosu i18n. Ta wtyczka utrzymuje synchronizację Twoich komunikatów JSON ze słownikami Intlayer, dzięki czemu możesz:
 
 - Zachować i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n itp.

package/docs/pt/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: Introduz validatePrefix e adiciona o passo 14: Tratamento de páginas 404 com rotas localizadas.
   - version: 7.3.9
     date: 2025-12-05
-    changes: Add step 13: Retrieve the locale in your server actions (Optional)
+    changes: Adiciona o passo 13: Recuperar o locale em suas server actions (Opcional)
   - version: 5.8.1
     date: 2025-09-09
     changes: Adicionado para Tanstack Start
@@ -612,7 +615,134 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Passo 14: Configurar o TypeScript (Opcional)
+### Passo 14: Gerenciar páginas não encontradas (Opcional)
+
+Quando um usuário visita uma página inexistente, você pode exibir uma página personalizada de não encontrada e o prefixo de locale pode afetar a forma como a página de não encontrada é acionada.
+
+#### Entendendo o tratamento de 404 do TanStack Router com prefixos de locale
+
+No TanStack Router, lidar com páginas 404 com rotas localizadas requer uma abordagem multicamadas:
+
+1. **Rota 404 dedicada**: Uma rota específica para exibir a interface 404
+2. **Validação no nível da rota**: Valida os prefixos de locale e redireciona os inválidos para 404
+3. **Rota catch-all**: Captura todos os caminhos não correspondentes dentro do segmento de locale
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// Isso cria uma rota dedicada /[locale]/404
+// É usada tanto como uma rota direta quanto importada como um componente em outros arquivos
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// Exportado separadamente para que possa ser reutilizado em notFoundComponent e rotas catch-all
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/__root.tsx"
+import { createRootRoute } from "@tanstack/react-router";
+
+// A rota raiz serve como o layout de nível superior
+// Ela não trata 404s diretamente - isso é delegado às rotas filhas
+// Isso mantém a raiz simples e permite que rotas conscientes de locale gerenciem sua própria lógica 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 executa antes da rota ser renderizada (tanto no servidor quanto no cliente)
+  // É o lugar ideal para validar o prefixo de locale
+  beforeLoad: ({ params }) => {
+    // Obter locale dos parâmetros da rota (não dos cabeçalhos do servidor, pois beforeLoad executa tanto no cliente quanto no servidor)
+    const localeParam = params.locale;
+
+    // validatePrefix verifica se o locale é válido de acordo com sua configuração intlayer
+    // Retorna: { isValid: boolean, localePrefix: string }
+    // - isValid: true se o prefixo corresponder a um locale configurado (ou estiver vazio quando o prefixo for opcional)
+    // - localePrefix: o prefixo validado ou o prefixo de locale padrão para redirecionamentos
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // Locale é válido, permitir que a rota seja renderizada normalmente
+      return;
+    }
+
+    // Prefixo de locale inválido (por exemplo, /xyz/about onde "xyz" não é um locale válido)
+    // Redirecionar para a página 404 com um prefixo de locale válido
+    // Isso garante que a página 404 ainda esteja adequadamente localizada
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent é chamado quando uma rota filha não existe
+  // por exemplo, /en/pagina-inexistente dispara isso dentro do layout /en
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // Envolver todo o segmento de locale com IntlayerProvider
+    // Volta para defaultLocale quando o parâmetro locale é undefined (modo de prefixo opcional)
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout envolve o componente 404 com IntlayerProvider
+// Isso garante que as traduções ainda funcionem na página 404
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* Incluir LocaleSwitcher para que os usuários possam alterar o idioma mesmo em 404 */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// A rota $ (splat/catch-all) corresponde a qualquer caminho que não corresponda a outras rotas
+// por exemplo, /en/algum/caminho/profundamente/aninhado/invalido
+// Isso garante que TODOS os caminhos não correspondentes dentro de um locale mostrem a página 404
+// Sem isso, caminhos profundos não correspondentes podem mostrar uma página em branco ou erro
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### Passo 15: Configurar o TypeScript (Opcional)
 
 O Intlayer utiliza a ampliação de módulos para aproveitar os benefícios do TypeScript e fortalecer sua base de código.