@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/uk/intlayer_with_tanstack.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-06-23
+updatedAt: 2026-08-25
 title: "TanStack Start i18n - Повний посібник з перекладу вашого застосунку"
 description: "Більше ніякого i18next. Посібник 2026 зі створення багатомовного (i18n) застосунку TanStack Start. Перекладайте за допомогою ШІ-агентів та оптимізуйте розмір бандлу, SEO та продуктивність."
 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: "Порівняння статичного, динамічного та кешованого динамічного розвʼязання словників метаданих у функціях head маршрутів"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Оновлення використання API useIntlayer у Solid для прямого доступу до властивостей"
@@ -57,7 +60,7 @@ author: aymericzip
 
 ## Чому варто обрати Intlayer, а не альтернативи?
 
-Порівняно з основними рішеннями, такими як `react-i18next` або `use-intl` або `paraglide`, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:
+Порівняно з основними рішеннями, такими як `react-i18next` або `use-intl` або `paraglide`, Intlayer пропонує рішення, яке має такі інтегровані оптимізації, як:
 
 <AccordionGroup>
 
@@ -317,14 +320,6 @@ function RootDocument({ children }: { children: ReactNode }) {
 }
 ```
 
-> Якщо ви хочете використовувати свій вміст в атрибуті типу `string`, наприклад `alt`, `title`, `href`, `aria-label` тощо, ви повинні викликати значення функції, наприклад:
-
-> ```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="Створіть Locale Layout">
@@ -516,13 +511,14 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="Використовуйте Intlayer на ваших сторінках">
 
+> Використовуйте **`useIntlayer`** за замовчуванням: це рекомендований спосіб читати контент усередині компонентів, і компілятор розвʼязує його у локаль, яка рендериться. Звертайтеся до `getIntlayer` / `getIntlayerAsync` лише поза деревом React: у `head` маршрутів, лоадерах і серверних функціях.
+
 Отримуйте доступ до словників контенту по всьому застосунку:
 
-#### Локалізована головна сторінка
+#### Локалізована домашня сторінка
 
 ```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";
@@ -560,13 +556,21 @@ function RouteComponent() {
 }
 ```
 
-> Щоб дізнатися більше про хук `useIntlayer`, зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useIntlayer.md).
+> Якщо ви хочете використовувати вміст у атрибуті `string`, такому як `alt`, `title`, `href`, `aria-label` тощо, ви можете використовувати значення функції, наприклад:
+>
+> ```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)}" />
+> ```
+
+> Щоб дізнатися більше про hook `useIntlayer`, звернітеся до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useIntlayer.md).
 
 </Step>
 
-<Step number={10} title="Створіть компонент перемикача локалі">
+<Step number={9} title="Створення компоненту перемикача локалей">
 
-Створіть компонент, щоб дозволити користувачам змінювати мову:
+Створіть компонент, щоб дозволити користувачам змінювати мови:
 
 ```tsx fileName="src/components/locale-switcher.tsx"
 import { useLocation } from "@tanstack/react-router";
@@ -600,19 +604,19 @@ export const LocaleSwitcher: FC = () => {
             to={pathWithoutLocale as To}
           >
             <span>
-              {/* Локаль, наприклад FR */}
+              {/* Локаль - наприклад FR */}
               {localeEl}
             </span>
             <span>
-              {/* Назва мови у власній локалі, наприклад Français */}
+              {/* Мова у своїй локалі - наприклад Français */}
               {getLocaleName(localeEl, locale)}
             </span>
             <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
-              {/* Мова в поточній локалі, наприклад «Francés», коли поточна локаль встановлена як Locales.SPANISH */}
+              {/* Мова в поточній локалі - наприклад Francés при встановленій поточній локалі на Locales.SPANISH */}
               {getLocaleName(localeEl)}
             </span>
             <span dir="ltr" lang={Locales.ENGLISH}>
-              {/* Мова англійською, наприклад «French» */}
+              {/* Мова англійською - наприклад French */}
               {getLocaleName(localeEl, Locales.ENGLISH)}
             </span>
           </LocalizedLink>
@@ -623,15 +627,17 @@ export const LocaleSwitcher: FC = () => {
 };
 ```
 
-> Щоб дізнатися більше про хук `useLocale`, зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useLocale.md).
+> Щоб дізнатися більше про hook `useLocale`, звернітеся до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useLocale.md).
 
 </Step>
 
-<Step number={11} title="Керування атрибутами HTML">
+<Step number={10} title="Управління HTML атрибутами">
 
-Як показано в Кроці 5, ви можете керувати атрибутами `lang` і `dir` тега `html`, використовуючи `useParams` у вашому кореневому компоненті. Це забезпечує правильне встановлення атрибутів на сервері та клієнті.
+Як видно з кроку 5, ви можете керувати атрибутами `lang` та `dir` тега `html` за допомогою `useParams` у вашому кореневому компоненті. Це забезпечує встановлення правильних атрибутів на сервері та клієнті.
 
 ```tsx fileName="src/routes/__root.tsx"
+const localeRoute = getRouteApi("/{-$locale}");
+
 function RootDocument({ children }: { children: ReactNode }) {
   const params = localeRoute.useParams();
   const locale = params?.locale ?? defaultLocale;
@@ -648,11 +654,13 @@ function RootDocument({ children }: { children: ReactNode }) {
 
 </Step>
 
-<Step number={12} title="Додати middleware">
+<Step number={11} title="Додавання middleware">
 
-Ви також можете використовувати `intlayerProxy` для додавання маршрутизації на стороні сервера у вашому додатку. Цей плагін автоматично визначатиме поточну локаль на основі URL і встановлюватиме відповідний cookie з локаллю. Якщо локаль не вказана, плагін визначить найбільш підходящу локаль на основі мовних налаштувань браузера користувача. Якщо локаль не буде виявлена, відбудеться перенаправлення на локаль за замовчуванням.
+Ви також можете використовувати `intlayerProxy` для додавання маршрутизації на стороні сервера до вашої програми. Цей плагін автоматично визначить поточну локаль на основі URL-адреси та встановить відповідну cookie-файл локалі. Якщо локаль не вказана, плагін визначить найбільш відповідну локаль на основі параметрів мови браузера користувача. Якщо локаль не виявлена, він перенаправить на локаль за замовчуванням.
 
-> Зверніть увагу, що щоб використовувати `intlayerProxy` у production, потрібно перемістити пакет `vite-intlayer` з `devDependencies` до `dependencies`.
+> Зауважте, що для використання `intlayerProxy` в production, вам потрібно переместити пакет `vite-intlayer` з `devDependencies` на `dependencies`.
+
+> З Intlayer v9, `intlayerProxy()` входить безпосередньо в плагін `intlayer()` і за замовчуванням увімкнено через параметр `routing.enableProxy` (`true` за замовчуванням). Реєстрація його окремо, як показано нижче, тепер опціональна: вона збережена для зворотної сумісності та для конфігурацій, які потребують контролю порядку плагінів. Встановіть `routing.enableProxy: false` для вимкнення. Див. [примітки до версії v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/releases/v9.md).
 
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
@@ -684,36 +692,99 @@ export default defineConfig({
 
 </Step>
 
-<Step number={13} title="Інтернаціоналізуйте свої метадані">
+<Step number={12} title="Інтернаціоналізація ваших метаданих">
 
-Ви також можете використовувати хук `getIntlayer`, щоб отримувати ваші словники контенту по всьому застосунку:
+<Tabs>
+
+<Tab label="Статичне розв'язання" value="static">
+
+`getIntlayer` синхронно розв'язує словник **об'єднаний**, той, який утримує кожну оголошену локаль. `head` залишається синхронним, і нічого не очікується, але весь багатомовний словник витягується в шматок маршруту, надісланий браузеру.
 
 ```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 = "/"; // Шлях для цього маршруту
 
     const metaContent = getIntlayer("app", locale);
 
     return {
       links: [
-        // Canonical link: Points to the current localized page
+        // Канонічне посилання: вказує на поточну локалізовану сторінку
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: повідомте Google про всі локалізовані версії
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: для користувачів неподібних мов
+        // Визначте локаль відступу за замовчуванням (зазвичай ваша основна мова)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: metaContent.title },
+        { name: "description", content: metaContent.meta.description },
+      ],
+    };
+  },
+});
+```
+
+Найкраще для невеликих словників метаданих, кількох локалей або під час прототипування.
+
+</Tab>
+
+<Tab label="Динамічне розв'язання" value="dynamic">
+
+`getIntlayerAsync` (доступно з **v9.4**) поводиться як `getIntlayer`, але плагін побудови вказує його на шматок для кожної локалі в `.intlayer/dynamic_dictionaries/` замість об'єднаного словника. Сторінка тому поставляється тільки локаллю, яку вона відображає. Оскільки цей шматок завантажується за запитом, `head` стає `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 = "/"; // Шлях для цього маршруту
+
+    const metaContent = await getIntlayerAsync("app", locale);
+
+    return {
+      links: [
+        // Канонічне посилання: вказує на поточну локалізовану сторінку
         { rel: "canonical", href: getLocalizedUrl(path, locale) },
 
-        // Hreflang: Tell Google about all localized versions
+        // Hreflang: повідомте Google про всі локалізовані версії
         ...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: для користувачів неподібних мов
+        // Визначте локаль відступу за замовчуванням (зазвичай ваша основна мова)
         {
           rel: "alternate",
           hrefLang: "x-default",
@@ -729,16 +800,99 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+> Якщо `head` читає кілька словників, розв'яжіть їх за допомогою `Promise.all`: очікування кожного `getIntlayerAsync` на власній лінії ланцюгує запити замість того, щоб запускати їх паралельно.
+
+Компромис: динамічний імпорт розв'язується під час виконання `head`, на критичному шляху рендерування документа. На холодному маршруті це затримує head на кілька мілісекунд і може трохи зменшити **LCP**.
+
+</Tab>
+
+<Tab label="Кешовано динамічне розв'язання" value="cached">
+
+Розв'яжіть словник у маршруті `loader` і прочитайте його назад із `loaderData` у `head`. Завантажувачі відповідних маршрутів запускаються паралельно, а `staleTime: Infinity` повідомляє TanStack Router, що результат ніколи не стає застарілим, тому шматок для кожної локалі розв'язується один раз і служить з кешу маршрутизатора після цього, залишаючи `head` синхронним.
+
+```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
+  loader: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+
+    return { metaContent: await getIntlayerAsync("app", locale) };
+  },
+  // Словник ніколи не змінюється для заданої локалі: розв'яжіть шматок один раз
+  staleTime: Infinity,
+  head: ({ params, loaderData }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // Шлях для цього маршруту
+
+    return {
+      links: [
+        // Канонічне посилання: вказує на поточну локалізовану сторінку
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: повідомте Google про всі локалізовані версії
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: для користувачів неподібних мов
+        // Визначте локаль відступу за замовчуванням (зазвичай ваша основна мова)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: loaderData?.metaContent.title },
+        {
+          name: "description",
+          content: loaderData?.metaContent.meta.description,
+        },
+      ],
+    };
+  },
+});
+```
+
+> `head` може бути викликаний до того, як завантажувач розв'яжеться, тому `loaderData` набирає тип як можливо `undefined`. Зберігайте необов'язковий ланцюг, або повертайте резервний заголовок.
+
+Ви зберігаєте шматок для кожної локалі без сплати його вартості на критичному шляху head. Ціна - досвід розробника: вміст має бути явно потокований із завантажувача до `head` через `loaderData`.
+
+</Tab>
+
+</Tabs>
+
+### Яку резолюцію вибрати?
+
+|                      | Статична резолюція    | Динамічна резолюція        | Кешована динамічна резолюція           |
+| -------------------- | --------------------- | -------------------------- | -------------------------------------- |
+| API                  | `getIntlayer`         | `getIntlayerAsync` (v9.4+) | `getIntlayerAsync` in `loader` (v9.4+) |
+| `head` signature     | synchronous           | `async`                    | synchronous, reads `loaderData`        |
+| Locales shipped      | every declared locale | requested locale only      | requested locale only                  |
+| Client navigations   | nothing to resolve    | re-entered on every match  | served from the router cache           |
+| Developer experience | simplest              | one `await`                | content threaded through `loaderData`  |
+
 ---
 
 </Step>
 
-<Step number={14} title="Отримання локалі у серверних діях">
+<Step number={13} title="Отримайте локаль у своїх серверних діях">
 
-Можливо, ви захочете отримувати поточну локаль всередині серверних дій або API-ендпоїнтів.
-Ви можете зробити це за допомогою хелпера `getLocale` з `intlayer`.
+Можливо, вам потрібно отримати доступ до поточної локалі всередині ваших серверних дій або API endpoints.
+Ви можете це зробити, використовуючи помічник `getLocale` з `intlayer`.
 
-Ось приклад із використанням серверних функцій TanStack Start:
+Ось приклад використання серверних функцій TanStack Start:
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createServerFn } from "@tanstack/react-start";
@@ -750,18 +904,18 @@ import { getCookie, getIntlayer, getLocale } from "intlayer";
 
 export const getLocaleServer = createServerFn().handler(async () => {
   const locale = await getLocale({
-    // Отримати cookie з запиту (за замовчуванням: 'INTLAYER_LOCALE')
+    // Отримайте cookie з запиту (за замовчуванням: 'INTLAYER_LOCALE')
     getCookie: (name) => {
       const cookieString = getRequestHeader("cookie");
 
       return getCookie(name, cookieString);
     },
-    // Отримати заголовок з запиту (за замовчуванням: 'x-intlayer-locale')
-    // Резервне відпрацювання через узгодження Accept-Language
+    // Отримайте заголовок з запиту (за замовчуванням: 'x-intlayer-locale')
+    // Резервний варіант за допомогою переговорів Accept-Language
     getHeader: (name) => getRequestHeader(name),
   });
 
-  // Отримати певний контент за допомогою getIntlayer()
+  // Отримайте деякий контент за допомогою getIntlayerAsync()
   const content = getIntlayer("app", locale);
 
   return { locale, content };
@@ -772,101 +926,132 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 </Step>
 
-<Step number={15} title="Керування сторінками «Не знайдено»">
+<Step number={14} title="Управління сторінками «не знайдено»">
 
-Коли користувач переходить на неіснуючу сторінку, ви можете відобразити власну сторінку «не знайдено», і префікс локалі може впливати на те, як ця сторінка викликається.
+Коли користувач відвідує неіснуючу сторінку, ви можете відобразити користувацьку сторінку «не знайдено» і префікс локалі може вплинути на те, як активується сторінка «не знайдено».
 
-#### Розуміння обробки 404 у TanStack Router з префіксами локалі
+#### Локалізована головна сторінка
 
-У TanStack Router обробка сторінок 404 для локалізованих маршрутів вимагає багаторівневого підходу:
+> Якщо ви хочете використовувати ваш вміст у атрибуті `string`, такому як `alt`, `title`, `href`, `aria-label` тощо, ви можете використовувати значення функції, як от:
+>
+> ```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. **Виділений маршрут 404**: спеціальний маршрут для відображення інтерфейсу сторінки 404
-2. **Валідація на рівні маршруту**: перевіряє префікси локалі та перенаправляє некоректні на 404
-3. **Catch-all route**: Перехоплює будь-які невідповідні шляхи в межах сегмента локалі
+> Щоб дізнатися більше про хук `useIntlayer`, зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useIntlayer.md).
 
-```tsx fileName="src/routes/{-$locale}/404.tsx"
-import { createFileRoute } from "@tanstack/react-router";
+</Step>
 
-// Це створює спеціальний маршрут /[locale]/404
-// Використовується як прямий маршрут і імпортується як компонент в інших файлах
-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);
 
-// Експортується окремо, щоб його можна було повторно використовувати в notFoundComponent та 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>
+              {/* Локаль, наприклад FR */}
+              {localeEl}
+            </span>
+            <span>
+              {/* Назва мови у власній локалі, наприклад Français */}
+              {getLocaleName(localeEl, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
+              {/* Мова в поточній локалі, наприклад «Francés», коли поточна локаль встановлена як Locales.SPANISH */}
+              {getLocaleName(localeEl)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Мова англійською, наприклад «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";
+> Щоб дізнатися більше про хук `useLocale`, зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useLocale.md).
 
-export const Route = createFileRoute("/{-$locale}")({
-  // beforeLoad виконується перед відображенням маршруту (як на сервері, так і на клієнті)
-  // Це ідеальне місце для валідації префіксу локалі
-  beforeLoad: ({ params }) => {
-    const localeParam = params.locale;
+</Step>
 
-    // validatePrefix перевіряє, чи дійсна локаль згідно з вашою конфігурацією intlayer
-    const { isValid, localePrefix } = validatePrefix(localeParam);
+<Step number={11} title="Керування атрибутами HTML">
 
-    if (!isValid) {
-      // Неприпустимий префікс локалі - перенаправити на сторінку 404 з дійсним префіксом локалі
-      throw redirect({
-        to: "/{-$locale}/404",
-        params: { locale: localePrefix },
-      });
-    }
-  },
-  component: Outlet,
-  // notFoundComponent викликається, коли дочірній маршрут не існує
-  // наприклад, /en/non-existent-page спричиняє це в межах layout для /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);
 
-// Маркер $ (splat/catch-all) маршрут відповідає будь-якому шляху, який не відповідає іншим маршрутам
-// наприклад, /en/some/deeply/nested/invalid/path
-// Це гарантує, що ВСІ невідповідні шляхи всередині локалі показуватимуть сторінку 404
-// Без цього, невідповідні глибокі шляхи можуть показувати порожню сторінку або викликати помилку
-export const Route = createFileRoute("/{-$locale}/$")({
-  component: NotFoundComponent,
-});
-```
+````
 
----
+> Якщо `head` читає кілька словників, розвʼязуйте їх через `Promise.all`: очікування кожного `getIntlayerAsync` окремим рядком вибудовує запити в ланцюжок замість паралельного виконання.
 
-</Step>
+Компроміс: динамічний імпорт розвʼязується під час виконання `head`, на критичному шляху рендерингу документа. На «холодному» маршруті це затримує `head` на кілька мілісекунд і може трохи погіршити **LCP**.
 
-<Step number={16} title="Налаштування TypeScript">
+</Tab>
 
-Intlayer використовує module augmentation, щоб отримати переваги TypeScript і зміцнити ваш codebase.
+<Tab label="Кешоване динамічне розвʼязання" value="cached">
 
-Переконайтеся, що ваша конфігурація TypeScript включає автогенеровані типи:
+Розвʼяжіть словник у `loader` маршруту й прочитайте його назад із `loaderData` у `head`. Лоадери збіглих маршрутів виконуються паралельно, а `staleTime: Infinity` повідомляє TanStack Router, що результат ніколи не застаріває, тож пер-локальний чанк розвʼязується один раз, а далі віддається з кешу роутера, лишаючи `head` синхронним.
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+
+1. **BLOCK 2 of 5** in English (en) shows only the opening `<Tabs>` and `<Tab value='Extract command'>` tags with no content following them.
+
+  return { locale, content };
+});
+import { createFileRoute } from "@tanstack/react-router";
+
+````
+
+```tsx fileName="src/routes/{-$locale}/route.tsx"
 
-```json5 fileName="tsconfig.json"
-{
-  // ... ваші наявні конфігурації
-  include: [
-    // ... ваші наявні includes
-    ".intlayer/**/*.ts", // Включає автогенеровані типи
-  ],
-}
 ```
 
----
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { NotFoundComponent } from "./404";
+```
 
 </Step>
 
@@ -881,24 +1066,11 @@ Intlayer використовує module augmentation, щоб отримати
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { type IntlayerConfig } from "intlayer";
 
-const config: IntlayerConfig = {
-  // ... Інша частина вашої конфігурації
-  compiler: {
-    /**
-     * Вказує, чи повинен бути включений компілятор.
-     */
-    enabled: true,
-
     /**
      * Визначає шлях до вихідних файлів
      */
     output: ({ fileName, extension }) => `./${fileName}${extension}`,
 
-    /**
-     * Вказує, чи повинні компоненти зберігатися після перетворення. Таким чином, компілятор можна запустити лише один раз для перетворення програми, а потім видалити.
-     */
-    saveComponents: false,
-
     /**
      * Префікс ключа словника
      */
@@ -915,29 +1087,23 @@ export default config;
 Запустіть екстрактор для перетворення компонентів і витягування вмісту
 
 ```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='Компілятор Babel'>
-
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+```bash packageManager="bun"
 
-Оновіть свій `vite.config.ts`, щоб включити плагін `intlayerCompiler`:
+</Tab>
+</Tabs>
 
-```ts fileName="vite.config.ts"
+bun x intlayer extract
 import { defineConfig } from "vite";
 import { intlayer, intlayerCompiler } from "vite-intlayer";
 
@@ -962,51 +1128,107 @@ yarn build # Or yarn dev
 ```
 
 ```bash packageManager="bun"
-bun run build # Or bun run dev
+
+---
+
+I'm ready to audit the translation. Please provide the content for **BLOCK 4 of 5** in both English (en) and Ukrainian (uk) so I can proceed with the audit.---
+
+export const pathList = ["", "/about", "/404"];
+
+const localizedPages = localeFlatMap(({ urlPrefix }) =>
+  pathList.map((path) => ({
+    path: `${urlPrefix}${path}`,
+    prerender: {
+      enabled: true,
+    },
+  }))
+);
+
+export default defineConfig({
+  plugins: [
+    // ... інші плагіни
+    tanstackStart({
+      // ... інша конфігурація
+      sitemap: {
+        enabled: false,
+      },
+      prerender: {
+        enabled: true,
+        crawlLinks: false,
+        concurrency: 10,
+      },
+      pages: localizedPages,
+    }),
+  ],
+});
 ```
 
- </Tab>
-</Tabs>
+Потім створіть маршрут `src/routes/sitemap[.]xml.ts`, який використовує функцію `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" },
+        });
+      },
+    },
+  },
+});
+{
+  // ... ваші існуючі конфігурації
+  include: [
+    // ... ваші існуючі включення
+    ".intlayer/**/*.ts", // Включіть автоматично згенеровані типи
+  ],
+}
 
-### Налаштування Git
+### Конфігурація Git
 
-Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволить уникнути їх коміту в ваш Git-репозиторій.
+Рекомендується ігнорувати файли, створені Intlayer. Це дозволяє вам уникнути їх фіксації у вашому Git репозиторію.
 
-Для цього ви можете додати наступні інструкції до файлу `.gitignore`:
+Для цього ви можете додати наступні інструкції до вашого файлу `.gitignore`:
 
 ```plaintext fileName=".gitignore"
-# Ігнорувати файли, згенеровані Intlayer
+# Ігнорувати файли, створені Intlayer
 .intlayer
-```
+````
 
 ---
 
 ## Розширення VS Code
 
-Щоб покращити досвід розробки з Intlayer, ви можете встановити офіційне **Intlayer VS Code Extension**.
+Щоб покращити ваш досвід розробки за допомогою Intlayer, ви можете встановити офіційне **розширення Intlayer VS Code Extension**.
 
 [Встановити з VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-Це розширення надає:
+Це розширення забезпечує:
 
-- **Автозаповнення** для ключів перекладу.
+- **Автодоповнення** для ключів перекладу.
 - **Виявлення помилок у реальному часі** для відсутніх перекладів.
-- **Вбудовані попередні перегляди** перекладеного вмісту.
+- **Вбудовані переглади** перекладеного контенту.
 - **Швидкі дії** для простого створення та оновлення перекладів.
 
-Для детальнішої інформації про використання розширення зверніться до [документації Intlayer VS Code Extension](https://intlayer.org/doc/vs-code-extension).
+Для детальнішої інформації про використання розширення див. [документацію розширення Intlayer VS Code Extension](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
-## Рухатися далі
+## Йти далі
 
-Щоб піти далі, ви можете реалізувати [візуальний редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md) або винести свій вміст у зовнішню систему, використовуючи [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md).
+Щоб йти далі, ви можете реалізувати [візуальний редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md) або екстерналізувати ваш вміст за допомогою [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md).
 
 ---
 
@@ -1014,7 +1236,7 @@ bun run build # Or bun run dev
 
 - [Документація Intlayer](https://intlayer.org)
 - [Документація Tanstack Start](https://reactrouter.com/)
-- [Хук useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useIntlayer.md)
-- [Хук useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useLocale.md)
-- [Оголошення контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md)
-- [Конфігурація](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)
+- [useIntlayer hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useIntlayer.md)
+- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useLocale.md)
+- [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)