@intlayer/docs 9.4.1 → 9.4.2

package/docs/uk/intlayer_with_tanstack.md

@@ -63,7 +63,6 @@ author: aymericzip
 Порівняно з основними рішеннями, такими як `react-i18next` або `use-intl` або `paraglide`, Intlayer пропонує рішення, яке має такі інтегровані оптимізації, як:
 
 <AccordionGroup>
-
 <Accordion header="Повна підтримка TanStack Start">
 
 Intlayer повністю оптимізовано для TanStack Start, забезпечуючи **багатомовну маршрутизацію**, **керування файлами cookie**, **генерацію карти сайту**, **динамічне завантаження вмісту** та всі функції, необхідні для масштабування ваших зусиль з інтернаціоналізації (i18n).
@@ -650,8 +649,6 @@ function RootDocument({ children }: { children: ReactNode }) {
 }
 ```
 
----
-
 </Step>
 
 <Step number={11} title="Додавання middleware">
@@ -688,8 +685,6 @@ export default defineConfig({
 });
 ```
 
----
-
 </Step>
 
 <Step number={12} title="Інтернаціоналізація ваших метаданих">
@@ -883,8 +878,6 @@ export const Route = createFileRoute("/{-$locale}/")({
 | 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={13} title="Отримайте локаль у своїх серверних діях">
@@ -922,140 +915,85 @@ export const getLocaleServer = createServerFn().handler(async () => {
 });
 ```
 
----
-
 </Step>
 
-<Step number={14} title="Управління сторінками «не знайдено»">
-
-Коли користувач відвідує неіснуючу сторінку, ви можете відобразити користувацьку сторінку «не знайдено» і префікс локалі може вплинути на те, як активується сторінка «не знайдено».
-
-#### Локалізована головна сторінка
-
-> Якщо ви хочете використовувати ваш вміст у атрибуті `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)}" />
-> ```
-
-> Щоб дізнатися більше про хук `useIntlayer`, зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useIntlayer.md).
+<Step number={14} title="Керування сторінками «Не знайдено»">
 
-</Step>
+Коли користувач переходить на неіснуючу сторінку, ви можете відобразити власну сторінку «не знайдено», і префікс локалі може впливати на те, як ця сторінка викликається.
 
-```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";
+#### Розуміння обробки 404 у TanStack Router з префіксами локалі
 
-import { LocalizedLink, type To } from "./localized-link";
+У TanStack Router обробка сторінок 404 для локалізованих маршрутів вимагає багаторівневого підходу:
 
-export const LocaleSwitcher: FC = () => {
-  const { pathname } = useLocation();
+1. **Виділений маршрут 404**: спеціальний маршрут для відображення інтерфейсу сторінки 404
+2. **Валідація на рівні маршруту**: перевіряє префікси локалі та перенаправляє некоректні на 404
+3. **Catch-all route**: Перехоплює будь-які невідповідні шляхи в межах сегмента локалі
 
-  const { availableLocales, locale, setLocale } = useLocale();
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
 
-  const pathWithoutLocale = getPathWithoutLocale(pathname);
+// Це створює спеціальний маршрут /[locale]/404
+// Використовується як прямий маршрут і імпортується як компонент в інших файлах
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
 
+// Експортується окремо, щоб його можна було повторно використовувати в notFoundComponent та catch-all маршрутах
+export function NotFoundComponent() {
   return (
-    <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>
+    <div>
+      <h1>404</h1>
+    </div>
   );
-};
-```
-
-> Щоб дізнатися більше про хук `useLocale`, зверніться до [документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/react-intlayer/useLocale.md).
-
-</Step>
-
-<Step number={11} title="Керування атрибутами HTML">
-
-return (
-<html dir={getHTMLTextDir(locale)} lang={locale}>
-{/* ... _/}
-</html>
-);
-} {/_ ... */}
-</html>
-);
 }
+```
 
-export const Route = createFileRoute("/{-$locale}/")({
-component: RouteComponent,
-head: async ({ params }) => {
-const { locale = defaultLocale } = params;
-const path = "/"; // The path for this route
-
-    const metaContent = await getIntlayerAsync("app", 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}/route.tsx"
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import { validatePrefix } from "intlayer";
+import { NotFoundComponent } from "./404";
 
-```tsx fileName="src/routes/{-$locale}/index.tsx"
+export const Route = createFileRoute("/{-$locale}")({
+  // beforeLoad виконується перед відображенням маршруту (як на сервері, так і на клієнті)
+  // Це ідеальне місце для валідації префіксу локалі
+  beforeLoad: ({ params }) => {
+    const localeParam = params.locale;
 
-1. **BLOCK 2 of 5** in English (en) shows only the opening `<Tabs>` and `<Tab value='Extract command'>` tags with no content following them.
+    // validatePrefix перевіряє, чи дійсна локаль згідно з вашою конфігурацією intlayer
+    const { isValid, localePrefix } = validatePrefix(localeParam);
 
-  return { locale, content };
+    if (!isValid) {
+      // Неприпустимий префікс локалі - перенаправити на сторінку 404 з дійсним префіксом локалі
+      throw redirect({
+        to: "/{-$locale}/404",
+        params: { locale: localePrefix },
+      });
+    }
+  },
+  component: Outlet,
+  // notFoundComponent викликається, коли дочірній маршрут не існує
+  // наприклад, /en/non-existent-page спричиняє це в межах layout для /en
+  notFoundComponent: NotFoundComponent,
 });
-import { createFileRoute } from "@tanstack/react-router";
-
-````
-
-```tsx fileName="src/routes/{-$locale}/route.tsx"
-
 ```
 
 ```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
 import { NotFoundComponent } from "./404";
+
+// Маркер $ (splat/catch-all) маршрут відповідає будь-якому шляху, який не відповідає іншим маршрутам
+// наприклад, /en/some/deeply/nested/invalid/path
+// Це гарантує, що ВСІ невідповідні шляхи всередині локалі показуватимуть сторінку 404
+// Без цього, невідповідні глибокі шляхи можуть показувати порожню сторінку або викликати помилку
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
 ```
 
 </Step>
 
-<Step number={1} title="Витягніть вміст ваших компонентів" isOptional={true}>
+<Step number={15} title="Витягніть вміст ваших компонентів" isOptional={true}> isOptional={true}>
 
 Якщо у вас є існуюча кодова база, перетворення тисяч файлів може зайняти багато часу.
 
@@ -1066,11 +1004,24 @@ import { NotFoundComponent } from "./404";
 ```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,
+
     /**
      * Префікс ключа словника
      */
@@ -1082,28 +1033,34 @@ export default config;
 ```
 
 <Tabs>
- <Tab value='Команда витягування'>
+ <Tab value="Команда витягування">
 
 Запустіть екстрактор для перетворення компонентів і витягування вмісту
 
 ```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>
-</Tabs>
+ </Tab>
+ <Tab value="Компілятор Babel">
 
-bun x intlayer extract
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
+Оновіть свій `vite.config.ts`, щоб включити плагін `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer, intlayerCompiler } from "vite-intlayer";
 
@@ -1128,10 +1085,25 @@ yarn build # Or yarn dev
 ```
 
 ```bash packageManager="bun"
+bun run build # Or bun run dev
+```
 
----
+ </Tab>
+</Tabs>
+
+</Step>
+
+<Step number={16} title="Pre-render & Generate Sitemap">
+
+Intlayer має вбудований генератор sitemap, який допомагає легко створити sitemap для вашої програми. Він обробляє локалізовані маршрути та додає необхідні метадані для пошукових систем.
 
-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.---
+> Карта сайту, згенерована Intlayer, підтримує простір імен `xhtml:link` (Hreflang XML Extensions). На відміну від генераторів карт сайту за замовчуванням, які лише перелічують необроблені URL-адреси, Intlayer автоматично створює необхідні двосторонні посилання між усіма мовними версіями сторінки (наприклад, `/about`, `/about?lang=fr` та `/about?lang=es`). Це забезпечує правильне індексування пошуковими системами та подачу правильної мовної версії відповідній аудиторії.
+
+Щоб використовувати це, спочатку потрібно налаштувати ваш `vite.config.ts` для увімкнення попередньої обробки локалізованих маршрутів і вимкнення генерування карти сайту TanStack Start за замовчуванням.
+
+```typescript fileName="vite.config.ts"
+import { localeFlatMap } from "intlayer";
+// ... інші імпорти
 
 export const pathList = ["", "/about", "/404"];
 
@@ -1165,9 +1137,13 @@ export default defineConfig({
 
 Потім створіть маршрут `src/routes/sitemap[.]xml.ts`, який використовує функцію `generateSitemap`:
 
-````typescript fileName="src/routes/sitemap[.]xml.ts"
+```typescript fileName="src/routes/sitemap[.]xml.ts"
+import { createFileRoute } from "@tanstack/react-router";
+import { generateSitemap } from "intlayer";
 
----
+const SITE_URL = (
+  import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
+).replace(/\/$/, "");
 
 export const Route = createFileRoute("/sitemap.xml")({
   server: {
@@ -1188,6 +1164,17 @@ export const Route = createFileRoute("/sitemap.xml")({
     },
   },
 });
+```
+
+</Step>
+
+<Step number={17} title="Налаштувати TypeScript">
+
+Intlayer використовує module augmentation для отримання переваг TypeScript та зміцнення вашого codebase.
+
+Переконайтеся, що ваша конфігурація TypeScript включає автоматично згенеровані типи:
+
+```json5 fileName="tsconfig.json"
 {
   // ... ваші існуючі конфігурації
   include: [
@@ -1195,17 +1182,22 @@ export const Route = createFileRoute("/sitemap.xml")({
     ".intlayer/**/*.ts", // Включіть автоматично згенеровані типи
   ],
 }
+```
 
-### Конфігурація Git
+</Step>
+
+</Steps>
+
+### Налаштування Git
 
-Рекомендується ігнорувати файли, створені Intlayer. Це дозволяє вам уникнути їх фіксації у вашому Git репозиторію.
+Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволить уникнути їх коміту в ваш Git-репозиторій.
 
-Для цього ви можете додати наступні інструкції до вашого файлу `.gitignore`:
+Для цього ви можете додати наступні інструкції до файлу `.gitignore`:
 
 ```plaintext fileName=".gitignore"
-# Ігнорувати файли, створені Intlayer
+# Ігнорувати файли, згенеровані Intlayer
 .intlayer
-````
+```
 
 ---
 
@@ -1240,3 +1232,114 @@ export const Route = createFileRoute("/sitemap.xml")({
 - [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)
+
+## Часто задавані запитання
+
+<FAQ>
+
+<Question title="Які є різні рішення для інтернаціоналізації додатків TanStack Start?">
+
+TanStack Start не має власного шару i18n:
+
+- **`i18next` / `react-i18next`** та **`react-intl`**: бібліотеки з завантаженням JSON під час виконання.
+- **`Intlayer`**: підтримка SSR та SSG, оголошення поруч із компонентом, повна типізація TypeScript, переклад AI та візуальний редактор.
+
+Див. [чому Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/interest_of_intlayer.md).
+
+</Question>
+
+<Question title="Скільки i18n додає до розміру бандла TanStack Start?">
+
+Значно менше, ніж рішення на основі просторів імен, оскільки сторінка ніколи не завантажує каталог, який вона не рендерить. Компілятор часу збирання замінює виклики `useIntlayer` точними записами словника, а [динамічні словники](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md) розділяють залишок за локалями, зменшуючи бандл до 50%. Див. [оптимізацію бандла](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/bundle_optimization.md) та [бенчмарк](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/benchmark/index.md).
+
+</Question>
+
+<Question title="Чи можу я мігрувати з react-i18next або react-intl без переписування компонентів?">
+
+Так, за допомогою посібників з міграції або адаптерів сумісності.
+
+</Question>
+
+<Question title="Чи можу я зберігати мої існуючі JSON файли перекладів?">
+
+Так. [sync JSON плагін](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/plugins/sync-json.md) зберігає ваші файли `/messages/{locale}/{namespace}.json` як джерело істини та генерує словники Intlayer з них в обох напрямках. [sync PO плагін](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/plugins/sync-po.md) робить те ж саме для gettext каталогів, а [файли для окремих локалей](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/per_locale_file.md) дозволяють розділити контент за мовами замість групування локалей в один файл.
+
+</Question>
+
+<Question title="Чи потрібно переносити вміст ключ за ключем?">
+
+Ні. Запустіть `npx intlayer extract`, і Intlayer прочитає ваші файли, витягне призначені для користувача рядки і створить файл `.content` поруч із кожним компонентом, завдяки чому ви переглядаєте diff замість копіювання рядків у каталог вручну.
+
+Для повної автоматизації [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/compiler.md) робить те саме під час збирання: сканує код під час кожної зміни, генерує словники та синхронізує їх із HMR.
+
+Варто знати два обмеження перед увімкненням компілятора. Він працює за допомогою статичного аналізу, тому рядки, які існують лише під час виконання, такі як коди помилок API або поля CMS, залишаються недосяжними. І він повинен відрізняти текст для користувача від логіки додатка, як-от `className="active"` або код статусу, що вимагає кількох анотацій у великій кодовій базі. [Команда extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/extract.md) уникає обох проблем, тримаючи вас у курсі.
+
+</Question>
+
+<Question title="Які інструменти для редактора та AI агентів доступні?">
+
+П'ять інструментів, усі опціональні:
+
+- **[Розширення VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/vs_code_extension.md)**: перехід від ключа `useIntlayer` до файлу контенту, вилучення рядків із компонента та запуск build, fill, test, push і pull із палітри команд або вкладки Intlayer.
+- **[LSP сервер](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/lsp.md)**: та сама функціональність у будь-якому редакторі з підтримкою LSP, включно з переходом до визначення, переглядом перекладеного значення під час наведення та автодоповненням ключів. Також підтримує виклики `i18next`, `react-i18next`, `next-intl` та `use-intl`.
+- **[MCP сервер](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/mcp_server.md)**: надає документацію та CLI Intlayer для Cursor, VS Code, Claude Desktop, Claude Code та ChatGPT.
+- **[Навички агента (Agent skills)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/agent_skills.md)**: спеціалізовані навички `intlayer-config`, `intlayer-cli` та `intlayer-content`.
+- **[Плагін ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/eslint.md)**: правило `no-raw-text` відстежує жорстко закодовані рядки.
+
+</Question>
+
+<Question title="Чи підтримує Intlayer серверний рендеринг та попередній рендеринг у TanStack Start?">
+
+Так. Контент вирішується під час SSR, і посібник охоплює конфігурацію попереднього рендерингу для кожної локалі.
+
+</Question>
+
+<Question title="Як додати теги hreflang та локалізовану карту сайту?">
+
+Використовуйте `generateSitemap` у маршруті `src/routes/sitemap[.]xml.ts` для генерації тегів `xhtml:link` та запису `x-default`.
+
+</Question>
+
+<Question title="Чи обов'язково додавати локаль до URL?">
+
+Ні. Налаштування `routing.mode` приймає `"prefix-no-default"` (за замовчуванням), `"prefix-all"`, `"no-prefix"` та `"search-params"`.
+
+</Question>
+
+<Question title="Як створити перемикач мов, який зберігає поточний маршрут?">
+
+Використовуйте `useLocale` у поєднанні з локалізованим компонентом посилання з кроку 9.
+
+</Question>
+
+<Question title="Як обробляти сторінки 404 у локалізованих маршрутах?">
+
+Крок 14 описує це. `validatePrefix` перевіряє валідність сегмента мови в URL.
+
+</Question>
+
+<Question title="Як автоматично перекласти додаток TanStack Start за допомогою AI?">
+
+Запустіть `npx intlayer fill`. Утиліта знаходить пропущені рядки та заповнює їх за допомогою обраної LLM. Див. [команду fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/fill.md).
+
+</Question>
+
+<Question title="Чи підтримує Intlayer форми множини, стать та форматований текст (rich text)?">
+
+Так: [форми множини](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/plurial.md), [контент з урахуванням статі](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/gender.md), умови, [вставки (insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/insertion.md), [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/markdown.md) та [форматування](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/formatters.md) чисел, дат і валют.
+
+</Question>
+
+<Question title="Як перекладачі можуть редагувати вміст без втручання в код?">
+
+Через [візуальний редактор](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), яка відокремлює вміст і дозволяє оновлювати його без повторного розгортання коду.
+
+</Question>
+
+<Question title="Чи є Intlayer безкоштовним та відкритим кодом?">
+
+Так, під ліцензією Apache 2.0, включно з комерційним використанням. Хмарна CMS - це додаткова платна послуга, яку також можна [розгорнути самостійно (self-host)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/self_hosting.md).
+
+</Question>
+
+</FAQ>

package/docs/uk/intlayer_with_vanilla.md

@@ -63,7 +63,6 @@ author: aymericzip
 Порівняно з основними рішеннями, такими як `i18next` або `i18n.js`, Intlayer — це рішення, яке поставляється з інтегрованою оптимізацією, як-от:
 
 <AccordionGroup>
-
 <Accordion header="Повна підтримка Vanilla JS">
 
 Intlayer оптимізовано для ідеальної роботи з Vanilla JavaScript, пропонуючи **незалежне від фреймворку керування вмістом**, **підтримку TypeScript** і всі функції, необхідні для масштабування інтернаціоналізації (i18n).
@@ -444,7 +443,8 @@ const unsubscribe = useDictionaryDynamic(
 ```
 
 > Примітка: `useDictionaryDynamic` вимагає, щоб словники були доступні у вигляді окремих файлів ESM. Цей підхід зазвичай використовується, якщо у вас є вебсервер, що роздає словники.
-> </Step>
+
+</Step>
 
 </Steps>
 
@@ -481,3 +481,111 @@ const unsubscribe = useDictionaryDynamic(
 ### Йдіть далі
 
 Щоб піти далі, ви можете впровадити [візуальний редактор](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).
+
+## Часто задавані запитання
+
+<FAQ>
+
+<Question title="Чи можу я використовувати Intlayer без бандлера або фреймворку?">
+
+Так. Цей посібник присвячений саме цьому. Ви підключаєте пакет `vanilla-intlayer` прямо в HTML, ініціалізуєте його та читаєте контент через `useIntlayer` або `getIntlayer`.
+
+</Question>
+
+<Question title="Скільки i18n додає до ваги моєї сторінки?">
+
+Значно менше, ніж традиційні каталоги, оскільки сторінка ніколи не завантажує мову, яку не рендерить. Вміст надається в оптимізованих форматах. Див. [оптимізацію бандла](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/bundle_optimization.md).
+
+</Question>
+
+<Question title="Чи можу я мігрувати з i18next без переписування скриптів?">
+
+Більшою мірою так. Дотримуйтесь [посібника з міграції з i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/migration_from_i18next_to_intlayer.md).
+
+</Question>
+
+<Question title="Чи можу я зберігати мої існуючі JSON файли перекладів?">
+
+Так. [sync JSON плагін](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/plugins/sync-json.md) зберігає ваші файли `/messages/{locale}/{namespace}.json` як джерело істини та генерує словники Intlayer з них в обох напрямках. [sync PO плагін](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/plugins/sync-po.md) робить те ж саме для gettext каталогів, а [файли для окремих локалей](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/per_locale_file.md) дозволяють розділити контент за мовами замість групування локалей в один файл.
+
+</Question>
+
+<Question title="Чи потрібно переносити вміст ключ за ключем?">
+
+Ні. Запустіть `npx intlayer extract`, і Intlayer прочитає ваші файли, витягне призначені для користувача рядки і створить файл `.content` поруч із кожним компонентом, завдяки чому ви переглядаєте diff замість копіювання рядків у каталог вручну. Див. [команду extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/extract.md).
+
+Для повної автоматизації [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/compiler.md) робить те саме під час збирання та генерує словники під час кожної зміни.
+
+</Question>
+
+<Question title="Які інструменти для редактора та AI агентів доступні?">
+
+П'ять інструментів, усі опціональні:
+
+- **[Розширення VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/vs_code_extension.md)**: перехід від ключа `useIntlayer` до файлу контенту, вилучення рядків із компонента та запуск build, fill, test, push і pull із палітри команд або вкладки Intlayer.
+- **[LSP сервер](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/lsp.md)**: та сама функціональність у будь-якому редакторі з підтримкою LSP, включно з переходом до визначення, переглядом перекладеного значення під час наведення та автодоповненням ключів. Також підтримує виклики `i18next`, `react-i18next`, `next-intl` та `use-intl`.
+- **[MCP сервер](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/mcp_server.md)**: надає документацію та CLI Intlayer для Cursor, VS Code, Claude Desktop, Claude Code та ChatGPT.
+- **[Навички агента (Agent skills)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/agent_skills.md)**: спеціалізовані навички `intlayer-config`, `intlayer-cli` та `intlayer-content`.
+- **[Плагін ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/eslint.md)**: правило `no-raw-text` відстежує жорстко закодовані рядки.
+
+</Question>
+
+<Question title="Які є різні рішення для інтернаціоналізації чистого JavaScript сайту?">
+
+- **Власний об'єкт словника**: без типізації та інструментів контролю якості.
+- **`i18next`**: універсальна бібліотека для runtime.
+- **`Intlayer`**: оголошення у файлах вмісту, опціональна компіляція під час збирання, типізація, візуальний редактор та CMS.
+
+Див. [чому Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/interest_of_intlayer.md).
+
+</Question>
+
+<Question title="Як прочитати переклад і вставити його в DOM?">
+
+Викликайте `useIntlayer` з ключем словника і встановіть значення у вузол DOM власноруч, як показано на кроці 6.
+
+</Question>
+
+<Question title="Як визначається мова відвідувача?">
+
+З джерел, перелічених у `routing.storage`: зазвичай спочатку cookie, потім заголовок `Accept-Language`, а далі мова за замовчуванням. Див. [довідник конфігурації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md).
+
+</Question>
+
+<Question title="Як підтримувати мови з написанням справа наліво?">
+
+Крок 8 описує це. `getHTMLTextDir` повертає `ltr`, `rtl` або `auto` для локалі, тому ви встановлюєте атрибути `lang` та `dir` на елементі `html` або `body`.
+
+</Question>
+
+<Question title="Чи завантажують відвідувачі кожну мову?">
+
+Ні, якщо ви цього не бажаєте. Крок 9 описує ліниве завантаження (lazy loading) словників за мовами, тому сторінка завантажує лише активну мову.
+
+</Question>
+
+<Question title="Як автоматично перекласти додаток за допомогою AI?">
+
+Запустіть `npx intlayer fill`. Утиліта заповнює відсутні переклади через обрану LLM з вашим провайдером та ключем API, а прапорець `--git-diff` обмежує обробку зміненими файлами. Див. [команду fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/fill.md) та [інтеграцію CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/CI_CD.md).
+
+</Question>
+
+<Question title="Чи підтримує Intlayer форми множини, стать та форматований текст (rich text)?">
+
+Так: [форми множини](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/plurial.md), [контент з урахуванням статі](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/gender.md), умови, [вставки (insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/insertion.md) та [форматування](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/formatters.md) чисел, дат і валют.
+
+</Question>
+
+<Question title="Як перекладачі можуть редагувати вміст без втручання в код?">
+
+Через [візуальний редактор](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), яка відокремлює вміст і дозволяє оновлювати його без повторного розгортання коду.
+
+</Question>
+
+<Question title="Чи є Intlayer безкоштовним та відкритим кодом?">
+
+Так, під ліцензією Apache 2.0, включно з комерційним використанням. Хмарна CMS - це додаткова платна послуга, яку також можна [розгорнути самостійно (self-host)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/self_hosting.md).
+
+</Question>
+
+</FAQ>