@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/pl/intlayer_with_tanstack.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-05-31
+updatedAt: 2026-08-25
 title: "TanStack Start i18n - Kompletny przewodnik po tłumaczeniu swojej aplikacji"
 description: "Koniec z i18next. Przewodnik 2026 do budowania wielojęzycznej (i18n) aplikacji TanStack Start. Tłumacz z agentami AI i optymalizuj rozmiar bundle, SEO i wydajność."
 keywords:
@@ -20,6 +20,9 @@ applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-templ
 applicationShowcase: https://intlayer-tanstack-start-template.vercel.app
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 9.4.0
+    date: 2026-08-25
+    changes: "Porównanie statycznego, dynamicznego i buforowanego dynamicznego rozwiązywania słowników metadanych w funkcjach head tras"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Aktualizacja użycia API useIntlayer w Solid do bezpośredniego dostępu do właściwości"
@@ -59,34 +62,51 @@ Ten przewodnik pokazuje, jak zintegrować **Intlayer** dla płynnej internacjona
 
 W porównaniu do głównych rozwiązań, takich jak „react-i18next”, „use-intl” lub „paraglide”, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:
 
+<AccordionGroup>
+
 **Pełne pokrycie TanStack Start**
 
 Intlayer jest w pełni zoptymalizowany pod kątem TanStack Start, zapewniając **wielojęzyczny routing**, **zarządzanie plikami cookie**, **generowanie mapy witryny**, **dynamiczne ładowanie treści** i wszystkie funkcje potrzebne do skalowania wysiłków związanych z internacjonalizacją (i18n).
 
+</Accordion>
+
 **Rozmiar bundle'a**
 
 Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga **zmniejszyć rozmiary bundle'a i stron nawet o 50%**.
 
+</Accordion>
+
 **Łatwość konserwacji**
 
 Określanie zakresu zawartości aplikacji **ułatwia konserwację** aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest **w pełni napisany**, aby zapewnić dokładność treści.
 
 **Agent AI**
 
+<Accordion header="Agent AI">
+
 Wspólna lokalizacja treści **zmniejsza potrzebny kontekst** dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak **CLI** do sprawdzania brakujących tłumaczeń**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** i **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/agent_skills.md)**, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.
 
+</Accordion>
+
 **Automatyzacja**
 
 Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także **kompilator** do automatyzacji ekstrakcji treści, a także [platformę internetową] (https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md), która pomaga **tłumaczyć w tle**.
 
 **Wydajność**
 
+<Accordion header="Wydajność">
+
 Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.
 
+</Accordion>
+
 **Skalowanie bez użycia dewelopera**
 
 Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia **samodzielny [edytor wizualny](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** i **[pełny CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**, który pomoże Ci zarządzać wielojęzyczną treścią w **w czasie rzeczywistym**, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.
 
+</Accordion>
+</AccordionGroup>
+
 ---
 
 ## Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Tanstack Start
@@ -300,14 +320,6 @@ function RootDocument({ children }: { children: ReactNode }) {
 }
 ```
 
-> Jeśli chcesz użyć swojej zawartości w atrybucie typu `string`, takim jak `alt`, `title`, `href`, `aria-label` itp., musisz wywołać wartość funkcji, na przykład:
-
-> ```html
-> <img src="{content.image.src.value}" alt="{content.image.value}" />
-> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
-> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
-> ```
-
 </Step>
 
 <Step number={6} title="Utwórz układ lokalizacji">
@@ -499,13 +511,14 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="Wykorzystaj Intlayer na swoich stronach">
 
+> Domyślnie używaj **`useIntlayer`**: to zalecany sposób odczytu treści wewnątrz komponentów, a kompilator rozwiązuje go do renderowanej lokalizacji. Po `getIntlayer` / `getIntlayerAsync` sięgaj tylko poza drzewem React: w `head` tras, loaderach i funkcjach serwerowych.
+
 Uzyskaj dostęp do swoich słowników treści w całej aplikacji:
 
-#### Lokalizowana strona główna
+#### Strona główna zlokalizowana
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createFileRoute } from "@tanstack/react-router";
-import { getIntlayer } from "intlayer";
 import { useIntlayer } from "react-intlayer";
 
 import LocaleSwitcher from "@/components/locale-switcher";
@@ -543,13 +556,21 @@ function RouteComponent() {
 }
 ```
 
-> Aby dowiedzieć się więcej o hooku `useIntlayer`, zapoznaj się z [dokumentacją](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useIntlayer.md).
+> Jeśli chcesz użyć zawartości w atrybucie `string`, takim jak `alt`, `title`, `href`, `aria-label` itd., możesz użyć wartości funkcji, na przykład:
+>
+> ```html
+> <img src="{content.image.src.value}" alt="{content.image.value}" />
+> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
+> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
+> ```
+
+> Aby dowiedzieć się więcej o hook'u `useIntlayer`, zapoznaj się z [dokumentacją](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useIntlayer.md).
 
 </Step>
 
-<Step number={10} title="Utwórz komponent przełącznika języka">
+<Step number={9} title="Utwórz komponent przełącznika języków">
 
-Utwórz komponent, który pozwoli użytkownikom zmieniać języki:
+Utwórz komponent umożliwiający użytkownikom zmianę języka:
 
 ```tsx fileName="src/components/locale-switcher.tsx"
 import { useLocation } from "@tanstack/react-router";
@@ -583,19 +604,19 @@ export const LocaleSwitcher: FC = () => {
             to={pathWithoutLocale as To}
           >
             <span>
-              {/* Lokalizacja - np. FR */}
+              {/* Locale - np. FR */}
               {localeEl}
             </span>
             <span>
-              {/* Język w swojej własnej lokalizacji - np. Français */}
+              {/* Język w jego własnym locale - np. Français */}
               {getLocaleName(localeEl, locale)}
             </span>
             <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
-              {/* Język w bieżącej lokalizacji - np. Francés przy ustawionej lokalizacji Locales.SPANISH */}
+              {/* Język w bieżącym locale - np. Francés przy bieżącym locale ustawionym na Locales.SPANISH */}
               {getLocaleName(localeEl)}
             </span>
             <span dir="ltr" lang={Locales.ENGLISH}>
-              {/* Język po angielsku - np. French */}
+              {/* Język w angielskim - np. French */}
               {getLocaleName(localeEl, Locales.ENGLISH)}
             </span>
           </LocalizedLink>
@@ -606,15 +627,17 @@ export const LocaleSwitcher: FC = () => {
 };
 ```
 
-> Aby dowiedzieć się więcej o hooku `useLocale`, zapoznaj się z [dokumentacją](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useLocale.md).
+> Aby dowiedzieć się więcej o hook'u `useLocale`, zapoznaj się z [dokumentacją](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useLocale.md).
 
 </Step>
 
-<Step number={11} title="Zarządzanie atrybutami HTML">
+<Step number={10} title="Zarządzanie atrybutami HTML">
 
-Jak pokazano w Kroku 5, możesz zarządzać atrybutami `lang` i `dir` tagu `html` za pomocą `useParams` w swoim komponencie głównym. Zapewnia to, że poprawne atrybuty są ustawione zarówno na serwerze, jak i kliencie.
+Jak pokazano w kroku 5, możesz zarządzać atrybutami `lang` i `dir` tagu `html` za pomocą `useParams` w komponencie głównym. Zapewnia to, że prawidłowe atrybuty są ustawione na serwerze i kliencie.
 
 ```tsx fileName="src/routes/__root.tsx"
+const localeRoute = getRouteApi("/{-$locale}");
+
 function RootDocument({ children }: { children: ReactNode }) {
   const params = localeRoute.useParams();
   const locale = params?.locale ?? defaultLocale;
@@ -631,11 +654,13 @@ function RootDocument({ children }: { children: ReactNode }) {
 
 </Step>
 
-<Step number={12} title="Dodaj middleware">
+<Step number={11} title="Dodaj middleware">
+
+Możesz także użyć `intlayerProxy` do dodania routingu po stronie serwera do aplikacji. Plugin ten automatycznie wykryje bieżący język na podstawie URL i ustawi odpowiedni plik cookie języka. Jeśli nie zostanie określony żaden język, plugin określi najbardziej odpowiedni język na podstawie preferencji języka przeglądarki użytkownika. Jeśli nie zostanie wykryty żaden język, nastąpi przekierowanie do języka domyślnego.
 
-Możesz również użyć `intlayerProxy`, aby dodać routing po stronie serwera do swojej aplikacji. Ten plugin automatycznie wykryje aktualną lokalizację na podstawie URL i ustawi odpowiednie ciasteczko lokalizacji. Jeśli nie zostanie określona żadna lokalizacja, plugin wybierze najbardziej odpowiednią na podstawie preferencji językowych przeglądarki użytkownika. Jeśli nie zostanie wykryta żadna lokalizacja, nastąpi przekierowanie do domyślnej.
+> Uwaga: aby użyć `intlayerProxy` w środowisku produkcyjnym, musisz przenieść pakiet `vite-intlayer` z `devDependencies` do `dependencies`.
 
-> Uwaga: aby używać `intlayerProxy` w produkcji, musisz przenieść pakiet `vite-intlayer` z `devDependencies` do `dependencies`.
+> Od Intlayer v9, `intlayerProxy()` jest bezpośrednio dołączony do pluginu `intlayer()` i domyślnie włączony za pośrednictwem opcji `routing.enableProxy` (`true` domyślnie). Rejestrowanie go osobno, jak pokazano poniżej, jest teraz opcjonalne: jest zachowywane dla kompatybilności wstecznej i dla ustawień, które muszą kontrolować kolejność pluginów. Ustaw `routing.enableProxy: false`, aby zrezygnować. Zapoznaj się z [notatkami do wydania v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/releases/v9.md).
 
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
@@ -667,36 +692,45 @@ export default defineConfig({
 
 </Step>
 
-<Step number={13} title="Internacjonalizacja metadanych">
+<Step number={12} title="Internationalizuj swoje metadane">
+
+<Tabs>
 
-Możesz również użyć hooka `getIntlayer`, aby uzyskać dostęp do słowników treści w całej aplikacji:
+<Tab label="Rozdzielczość statyczna" value="static">
+
+`getIntlayer` rozwiązuje się synchronicznie względem **scalonego** słownika, tego zawierającego każdy zadeklarowany język. `head` pozostaje synchroniczny i nic nie jest oczekiwane, ale cały wielojęzyczny słownik jest pobierany do fragmentu trasy wysyłanego do przeglądarki.
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createFileRoute } from "@tanstack/react-router";
-import { getIntlayer } from "intlayer";
+import {
+  defaultLocale,
+  getIntlayer,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
-    const { locale } = params;
-    const path = "/"; // The path for this route
+    const { locale = defaultLocale } = params;
+    const path = "/"; // Ścieżka dla tej trasy
 
     const metaContent = getIntlayer("app", locale);
 
     return {
       links: [
-        // Canonical link: Points to the current localized page
+        // Link kanoniczny: wskazuje na bieżącą stronę zlokalizowaną
         { rel: "canonical", href: getLocalizedUrl(path, locale) },
 
-        // Hreflang: Tell Google about all localized versions
+        // Hreflang: powiadomi Google o wszystkich zlokalizowanych wersjach
         ...localeMap(({ locale: mapLocale }) => ({
           rel: "alternate",
           hrefLang: mapLocale,
           href: getLocalizedUrl(path, mapLocale),
         })),
 
-        // x-default: For users in unmatched languages
-        // Define the default fallback locale (usually your primary language)
+        // x-default: dla użytkowników w niedopasowanych językach
+        // Zdefiniuj domyślny fallback locale (zwykle Twój język podstawowy)
         {
           rel: "alternate",
           hrefLang: "x-default",
@@ -712,16 +746,153 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+Najlepsze dla małych słowników metadanych, kilku locale'i lub podczas prototypowania.
+
+</Tab>
+
+<Tab label="Rozdzielczość dynamiczna" value="dynamic">
+
+`getIntlayerAsync` (dostępne od **v9.4**) zachowuje się jak `getIntlayer`, ale plugin budowania wskazuje go na fragment dla konkretnego locale'a w `.intlayer/dynamic_dictionaries/` zamiast scalonego słownika. Strona zatem wysyła tylko locale, który renderuje. Ponieważ fragment jest ładowany na żądanie, `head` staje się `async`:
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // Ścieżka dla tej trasy
+
+    const metaContent = await getIntlayerAsync("app", locale);
+
+    return {
+      links: [
+        // Link kanoniczny: wskazuje na bieżącą stronę zlokalizowaną
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: powiadomi Google o wszystkich zlokalizowanych wersjach
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: dla użytkowników w niedopasowanych językach
+        // Zdefiniuj domyślny fallback locale (zwykle Twój język podstawowy)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: metaContent.title },
+        { name: "description", content: metaContent.meta.description },
+      ],
+    };
+  },
+});
+```
+
+> Jeśli `head` odczytuje kilka słowników, rozwiąż je za pomocą `Promise.all`: oczekiwanie każdego `getIntlayerAsync` w oddzielnej linii łańcuchuje żądania zamiast uruchamiać je równolegle.
+
+Kompromis: import dynamiczny jest rozwiązywany podczas uruchamiania `head`, na krytycznej ścieżce renderowania dokumentu. Na zimnej trasie opóźnia to head o kilka milisekund i może nieco pogorszyć **LCP**.
+
+</Tab>
+
+<Tab label="Rozdzielczość dynamiczna buforowana" value="cached">
+
+Rozwiąż słownik w `loader` trasy i przeczytaj go z powrotem z `loaderData` w `head`. Loadery dopasowanych tras działają równolegle, a `staleTime: Infinity` mówi TanStack Router, że wynik nigdy się nie starzeje, więc fragment dla konkretnego locale'a jest rozwiązywany raz i podawany z cache'a routera później, pozostawiając `head` synchroniczny.
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  // Rozwiązywany równolegle z innymi dopasowanymi trasami, poza krytyczną ścieżką head
+  loader: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+
+    return { metaContent: await getIntlayerAsync("app", locale) };
+  },
+  // Słownik nigdy się nie zmienia dla danego locale: rozwiąż fragment raz
+  staleTime: Infinity,
+  head: ({ params, loaderData }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // Ścieżka dla tej trasy
+
+    return {
+      links: [
+        // Link kanoniczny: wskazuje na bieżącą stronę zlokalizowaną
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: powiadomi Google o wszystkich zlokalizowanych wersjach
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: dla użytkowników w niedopasowanych językach
+        // Zdefiniuj domyślny fallback locale (zwykle Twój język podstawowy)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: loaderData?.metaContent.title },
+        {
+          name: "description",
+          content: loaderData?.metaContent.meta.description,
+        },
+      ],
+    };
+  },
+});
+```
+
+> `head` może być wywoływany przed osadzeniem loadera, więc `loaderData` jest wpisywana jako możliwie `undefined`. Zachowaj opcjonalne łańcuchowanie lub zwróć tytuł fallback.
+
+Zachowujesz fragment dla konkretnego locale'a bez płacenia jego kosztu na krytycznej ścieżce head. Cena to doświadczenie deweloperskie: zawartość musi być jawnie przekazywana z loadera do `head` poprzez `loaderData`.
+
+</Tab>
+
+</Tabs>
+
+### Którą rozdzielczość powinienem wybrać?
+
+|                          | Rozdzielczość statyczna    | Rozdzielczość dynamiczna                   | Rozdzielczość dynamiczna z cache'em    |
+| ------------------------ | -------------------------- | ------------------------------------------ | -------------------------------------- |
+| API                      | `getIntlayer`              | `getIntlayerAsync` (v9.4+)                 | `getIntlayerAsync` w `loader` (v9.4+)  |
+| Sygnatura `head`         | synchroniczna              | `async`                                    | synchroniczna, czyta `loaderData`      |
+| Ustawienia regionalne    | każdy zadeklarowany locale | tylko żądany locale                        | tylko żądany locale                    |
+| Nawigacja na kliencie    | nic do rozwiązania         | ponownie wznawiane przy każdym dopasowaniu | obsługiwane z cache'u routera          |
+| Doświadczenie dewelopera | najprostsze                | jedno `await`                              | zawartość przesłana przez `loaderData` |
+
 ---
 
 </Step>
 
-<Step number={14} title="Pobieranie lokalizacji w akcjach serwerowych">
+<Step number={13} title="Pobierz locale w swoich server actions">
 
-Możesz chcieć uzyskać dostęp do aktualnej lokalizacji wewnątrz swoich akcji serwerowych lub punktów końcowych API.
-Możesz to zrobić za pomocą pomocnika `getLocale` z `intlayer`.
+Możesz chcieć uzyskać dostęp do bieżącego locale'a z wnętrza twoich server actions lub API endpoints.
+Możesz to zrobić używając helpera `getLocale` z `intlayer`.
 
-Oto przykład użycia funkcji serwerowych TanStack Start:
+Oto przykład używający server functions TanStack Start:
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createServerFn } from "@tanstack/react-start";
@@ -733,18 +904,18 @@ import { getCookie, getIntlayer, getLocale } from "intlayer";
 
 export const getLocaleServer = createServerFn().handler(async () => {
   const locale = await getLocale({
-    // Pobierz ciasteczko z żądania (domyślnie: 'INTLAYER_LOCALE')
+    // Pobierz cookie z żądania (domyślnie: 'INTLAYER_LOCALE')
     getCookie: (name) => {
       const cookieString = getRequestHeader("cookie");
 
       return getCookie(name, cookieString);
     },
     // Pobierz nagłówek z żądania (domyślnie: 'x-intlayer-locale')
-    // Rezerwowe rozwiązanie przy użyciu negocjacji Accept-Language
+    // Fallback używający negocjacji Accept-Language
     getHeader: (name) => getRequestHeader(name),
   });
 
-  // Pobierz treść za pomocą getIntlayer()
+  // Pobierz zawartość używając getIntlayerAsync()
   const content = getIntlayer("app", locale);
 
   return { locale, content };
@@ -755,101 +926,155 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 </Step>
 
-<Step number={15} title="Zarządzanie stronami &quot;nie znaleziono&quot;">
+<Step number={14} title="Zarządzaj stronami not found">
 
-Gdy użytkownik odwiedza nieistniejącą stronę, możesz wyświetlić niestandardową stronę "nie znaleziono", a prefiks lokalizacji może wpływać na sposób wyzwalania strony "nie znaleziono".
+Gdy użytkownik odwiedzi nieistniejącą stronę, możesz wyświetlić niestandardową stronę not found, a prefiks locale'a może wpłynąć na sposób, w jaki strona not found jest wyzwalana.
 
-#### Zrozumienie obsługi 404 w TanStack Router z prefiksami lokalizacji
+#### Lokalizowana strona główna
 
-W TanStack Router obsługa stron 404 z zlokalizowanymi trasami wymaga podejścia wielowarstwowego:
+> Jeśli chcesz użyć swojej zawartości w atrybucie `string`, takim jak `alt`, `title`, `href`, `aria-label`, itp., możesz użyć wartości funkcji, na przykład:
+>
+> ```html
+> <img src="{content.image.src.value}" alt="{content.image.value}" />
+> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
+> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
+> ```
 
-1. **Dedykowana trasa 404**: Konkretna trasa do wyświetlenia interfejsu 404
-2. **Walidacja na poziomie trasy**: Weryfikuje prefiksy lokalizacji i przekierowuje nieprawidłowe do 404
-3. **Trasa catch-all**: Przechwytuje wszystkie niedopasowane ścieżki w segmencie lokalizacji
+> Aby dowiedzieć się więcej o hooku `useIntlayer`, zapoznaj się z [dokumentacją](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useIntlayer.md).
 
-```tsx fileName="src/routes/{-$locale}/404.tsx"
-import { createFileRoute } from "@tanstack/react-router";
+</Step>
 
-// 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,
-});
+```tsx fileName="src/components/locale-switcher.tsx"
+import { useLocation } from "@tanstack/react-router";
+import {
+  getHTMLTextDir,
+  getLocaleName,
+  getPathWithoutLocale,
+  getPrefix,
+  Locales,
+} from "intlayer";
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+import { LocalizedLink, type To } from "./localized-link";
+
+export const LocaleSwitcher: FC = () => {
+  const { pathname } = useLocation();
+
+  const { availableLocales, locale, setLocale } = useLocale();
+
+  const pathWithoutLocale = getPathWithoutLocale(pathname);
 
-// 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>
+    <ol>
+      {availableLocales.map((localeEl) => (
+        <li key={localeEl}>
+          <LocalizedLink
+            aria-current={localeEl === locale ? "page" : undefined}
+            onClick={() => setLocale(localeEl)}
+            params={{ locale: getPrefix(localeEl).localePrefix }}
+            to={pathWithoutLocale as To}
+          >
+            <span>
+              {/* Lokalizacja - np. FR */}
+              {localeEl}
+            </span>
+            <span>
+              {/* Język w swojej własnej lokalizacji - np. Français */}
+              {getLocaleName(localeEl, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
+              {/* Język w bieżącej lokalizacji - np. Francés przy ustawionej lokalizacji Locales.SPANISH */}
+              {getLocaleName(localeEl)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Język po angielsku - np. French */}
+              {getLocaleName(localeEl, Locales.ENGLISH)}
+            </span>
+          </LocalizedLink>
+        </li>
+      ))}
+    </ol>
   );
-}
+};
 ```
 
-```tsx fileName="src/routes/{-$locale}/route.tsx"
-import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
-import { validatePrefix } from "intlayer";
-import { NotFoundComponent } from "./404";
+> Aby dowiedzieć się więcej o hooku `useLocale`, zapoznaj się z [dokumentacją](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useLocale.md).
 
-export const Route = createFileRoute("/{-$locale}")({
-  // beforeLoad uruchamia się przed renderowaniem trasy (zarówno na serwerze, jak i kliencie)
-  // To idealne miejsce do walidacji prefiksu lokalizacji
-  beforeLoad: ({ params }) => {
-    const localeParam = params.locale;
+</Step>
 
-    // validatePrefix sprawdza, czy lokalizacja jest prawidłowa zgodnie z konfiguracją intlayer
-    const { isValid, localePrefix } = validatePrefix(localeParam);
+<Step number={11} title="Zarządzanie atrybutami HTML">
 
-    if (!isValid) {
-      // Nieprawidłowy prefiks lokalizacji - przekieruj do strony 404 z prawidłowym prefiksem lokalizacji
-      throw redirect({
-        to: "/{-$locale}/404",
-        params: { locale: localePrefix },
-      });
-    }
-  },
-  component: Outlet,
-  // notFoundComponent jest wywoływane, gdy trasa potomna nie istnieje
-  // np. /en/nieistniejaca-strona wyzwala to w układzie /en
-  notFoundComponent: NotFoundComponent,
-});
-```
+return (
+<html dir={getHTMLTextDir(locale)} lang={locale}>
+{/* ... _/}
+</html>
+);
+} {/_ ... */}
+</html>
+);
+}
 
-```tsx fileName="src/routes/{-$locale}/$.tsx"
-import { createFileRoute } from "@tanstack/react-router";
+export const Route = createFileRoute("/{-$locale}/")({
+component: RouteComponent,
+head: async ({ params }) => {
+const { locale = defaultLocale } = params;
+const path = "/"; // The path for this route
 
-import { NotFoundComponent } from "./404";
+    const metaContent = await getIntlayerAsync("app", locale);
 
-// 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 lokalizacji 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,
-});
-```
+````
+
+> Jeśli `head` czyta kilka słowników, rozwiąż je przez `Promise.all`; oczekiwanie na każde `getIntlayerAsync` w osobnej linii łańcuchuje żądania zamiast wykonywać je równolegle.
+
+Kompromis: dynamiczny import jest rozwiązywany w trakcie działania `head`, na ścieżce krytycznej renderowania dokumentu. Na „zimnej” trasie opóźnia to `head` o kilka milisekund i może nieznacznie pogorszyć **LCP**.
+
+</Tab>
+
+<Tab label="Buforowane rozwiązywanie dynamiczne" value="cached">
+
+Rozwiąż słownik w `loaderze` trasy i odczytaj go z `loaderData` w `head`. Loadery dopasowanych tras działają równolegle, a `staleTime: Infinity` informuje TanStack Router, że wynik nigdy się nie dezaktualizuje, fragment per-lokalizacja jest więc rozwiązywany raz, a potem serwowany z cache routera, pozostawiając `head` synchronicznym.
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+      return getCookie(name, cookieString);
+    },
+    // Pobierz nagłówek z żądania (domyślnie: 'x-intlayer-locale')
+    // Rezerwowe rozwiązanie przy użyciu negocjacji Accept-Language
+    getHeader: (name) => getRequestHeader(name),
+  });
+
+  // Pobierz treść za pomocą getIntlayer()
+  const content = getIntlayer("app", locale);
+
+````
 
 ---
 
 </Step>
 
-<Step number={16} title="Konfiguracja TypeScript">
+<Step number={15} title="Zarządzanie stronami &quot;nie znaleziono&quot;">
 
-Intlayer używa rozszerzenia modułów (module augmentation), aby wykorzystać zalety TypeScript i wzmocnić Twoją bazę kodu.
+Gdy użytkownik odwiedza nieistniejącą stronę, możesz wyświetlić niestandardową stronę "nie znaleziono", a prefiks lokalizacji może wpływać na sposób wyzwalania strony "nie znaleziono".
 
-Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy:
+#### Zrozumienie obsługi 404 w TanStack Router z prefiksami lokalizacji
+
+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 lokalizacji i przekierowuje nieprawidłowe do 404
+3. **Trasa catch-all**: Przechwytuje wszystkie niedopasowane ścieżki w segmencie lokalizacji
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
 
-```json5 fileName="tsconfig.json"
-{
-  // ... Twoje istniejące konfiguracje
-  include: [
-    // ... Twoje istniejące include
-    ".intlayer/**/*.ts", // Dołącz automatycznie generowane typy
-  ],
-}
 ```
 
----
+```tsx fileName="src/routes/{-$locale}/route.tsx"
+
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+
+```
 
 </Step>
 
@@ -864,24 +1089,11 @@ Aby go skonfigurować, możesz dodać sekcję `compiler` w pliku `intlayer.confi
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { type IntlayerConfig } from "intlayer";
 
-const config: IntlayerConfig = {
-  // ... Reszta Twojej konfiguracji
-  compiler: {
-    /**
-     * Wskazuje, czy kompilator powinien być włączony.
-     */
-    enabled: true,
-
     /**
      * Definiuje ścieżkę plików wyjściowych
      */
     output: ({ fileName, extension }) => `./${fileName}${extension}`,
 
-    /**
-     * Wskazuje, czy komponenty powinny zostać zapisane po transformacji. W ten sposób kompilator można uruchomić tylko raz, aby przetransformować aplikację, a następnie go usunąć.
-     */
-    saveComponents: false,
-
     /**
      * Prefiks klucza słownika
      */
@@ -898,29 +1110,23 @@ export default config;
 Uruchom ekstraktor, aby przetransformować komponenty i wyodrębnić zawartość
 
 ```bash packageManager="npm"
-npx intlayer extract
+
 ```
 
 ```bash packageManager="pnpm"
-pnpm intlayer extract
+
 ```
 
 ```bash packageManager="yarn"
-yarn intlayer extract
+
 ```
 
 ```bash packageManager="bun"
-bun x intlayer extract
-```
 
  </Tab>
- <Tab value='Kompilator Babel'>
-
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Zaktualizuj `vite.config.ts`, aby dołączyć wtyczkę `intlayerCompiler`:
+</Tabs>
 
-```ts fileName="vite.config.ts"
+bun x intlayer extract
 import { defineConfig } from "vite";
 import { intlayer, intlayerCompiler } from "vite-intlayer";
 
@@ -945,59 +1151,117 @@ yarn build # Or yarn dev
 ```
 
 ```bash packageManager="bun"
+
+---
+
 bun run build # Or bun run dev
+import { localeFlatMap } from "intlayer";
+// ... inne importy
+
+export const pathList = ["", "/about", "/404"];
+
+const localizedPages = localeFlatMap(({ urlPrefix }) =>
+  pathList.map((path) => ({
+    path: `${urlPrefix}${path}`,
+    prerender: {
+      enabled: true,
+    },
+  }))
+);
+
+export default defineConfig({
+  plugins: [
+    // ... pozostałe wtyczki
+    tanstackStart({
+      // ... pozostała konfiguracja
+      sitemap: {
+        enabled: false,
+      },
+      prerender: {
+        enabled: true,
+        crawlLinks: false,
+        concurrency: 10,
+      },
+      pages: localizedPages,
+    }),
+  ],
+});
 ```
 
- </Tab>
-</Tabs>
+Następnie utwórz trasę `src/routes/sitemap[.]xml.ts`, która wykorzystuje funkcję `generateSitemap`:
 
----
+````typescript fileName="src/routes/sitemap[.]xml.ts"
 
-</Step>
+---
 
-</Steps>
+export const Route = createFileRoute("/sitemap.xml")({
+  server: {
+    handlers: {
+      GET: async () => {
+        const sitemap = generateSitemap(
+          [
+            { path: "/", changefreq: "daily", priority: 1.0 },
+            { path: "/about", changefreq: "monthly", priority: 0.8 },
+          ],
+          { siteUrl: SITE_URL }
+        );
+
+        return new Response(sitemap, {
+          headers: { "Content-Type": "application/xml" },
+        });
+      },
+    },
+  },
+});
+{
+  // ... twoje istniejące konfiguracje
+  include: [
+    // ... twoje istniejące includy
+    ".intlayer/**/*.ts", // Dołącz auto-generowane typy
+  ],
+}
 
 ### Konfiguracja Git
 
-Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania do repozytorium Git.
+Zaleca się ignorować pliki generowane przez Intlayer. Pozwala to uniknąć zatwierdzania ich w repozytorium Git.
 
 Aby to zrobić, możesz dodać następujące instrukcje do pliku `.gitignore`:
 
 ```plaintext fileName=".gitignore"
 # Ignoruj pliki generowane przez Intlayer
 .intlayer
-```
+````
 
 ---
 
 ## Rozszerzenie VS Code
 
-Aby poprawić swoje doświadczenie deweloperskie z Intlayer, możesz zainstalować oficjalne **rozszerzenie Intlayer dla VS Code**.
+Aby ulepszyć doświadczenie programistyczne dzięki Intlayer, możesz zainstalować oficjalne **rozszerzenie Intlayer dla VS Code**.
 
-[Zainstaluj z Marketplace VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+[Zainstaluj z VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-To rozszerzenie oferuje:
+To rozszerzenie zapewnia:
 
-- **Autouzupełnianie** kluczy tłumaczeń.
+- **Autouzupełnianie** dla kluczy tłumaczeń.
 - **Wykrywanie błędów w czasie rzeczywistym** dla brakujących tłumaczeń.
-- **Podgląd w linii** przetłumaczonej zawartości.
-- **Szybkie akcje** umożliwiające łatwe tworzenie i aktualizowanie tłumaczeń.
+- **Podglądy inline** przetłumaczonej zawartości.
+- **Szybkie akcje** do łatwego tworzenia i aktualizacji tłumaczeń.
 
-Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj się z [dokumentacją rozszerzenia Intlayer VS Code](https://intlayer.org/doc/vs-code-extension).
+Aby uzyskać więcej szczegółów na temat korzystania z rozszerzenia, zapoznaj się z [dokumentacją rozszerzenia Intlayer VS Code Extension](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
 ## 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).
+Aby pójść dalej, możesz wdrożyć [edytor wizualny](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_visual_editor.md) lub externalizować swoją zawartość przy użyciu [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md).
 
 ---
 
-## Odnośniki do dokumentacji
+## Referencje Dokumentacji
 
 - [Dokumentacja Intlayer](https://intlayer.org)
 - [Dokumentacja Tanstack Start](https://reactrouter.com/)
-- [Hook useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useIntlayer.md)
-- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useLocale.md)
-- [Deklaracja treści](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md)
+- [hook useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useIntlayer.md)
+- [hook useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/react-intlayer/useLocale.md)
+- [Deklaracja Zawartości](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dictionary/content_file.md)
 - [Konfiguracja](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)