@intlayer/docs 7.5.11 → 7.5.13

package/frequent_questions/uk/error-vite-env-only.md

@@ -0,0 +1,77 @@
+---
+createdAt: 2026-01-11
+updatedAt: 2026-01-11
+title: `vite-env-only` & Intlayer – хибнопозитивна помилка відхилення `node:fs`
+description: Чому vite-env-only повідомляє про відхилений імпорт `node:fs` з Intlayer + React-Router + Vite і що робити.
+keywords:
+  - intlayer
+  - vite
+  - react-router
+  - vite-env-only
+  - node:fs
+  - відхилений імпорт
+  - alias
+  - клієнтський бандл
+slugs:
+  - frequent-questions
+  - vite-env-only-node-fs-false-positive
+---
+
+# vite-env-only відхиляє `node:fs` в Intlayer
+
+Якщо ви використовували плагін **vite-env-only** (як зазначено в старих рекомендаціях React-Router v7) і бачите:
+
+```bash
+
+Error: [vite-env-only] Import denied
+
+* Denied by specifier pattern: /^node:/
+* Importer: index.html
+* Import: "node:fs"
+
+```
+
+…незважаючи на те, що **в клієнтському бандлі немає `node:fs`**, це — **хибне спрацювання**.
+
+## Чому це відбувається
+
+`vite-env-only` виконує перевірку на основі Babel **на ранньому етапі резолюції графа Vite**, _перед_:
+
+- aliasing (включаючи відповідності Intlayer для browser vs node),
+- dead-code elimination,
+- SSR vs client resolution,
+- віртуальні модулі, як-от ті в React-Router.
+
+Пакети Intlayer містять код, який може працювати як у Node, так і в браузері. На _проміжному_ етапі в графі може з'явитися вбудований модуль Node, наприклад `node:fs`, **перед тим як** Vite видалить його з клієнтської збірки. `vite-env-only` помічає це і відразу видає помилку, хоча у фінальному бандлі його немає.
+
+## React-Router і серверні модулі
+
+У документації React-Router щодо **конвенцій серверних модулів**
+(https://reactrouter.com/api/framework-conventions/server-modules), команда **чітко рекомендує використовувати `vite-env-only`**, щоб запобігти потраплянню імпортів, призначених лише для сервера, у клієнтський бандл.
+
+Однак ці конвенції покладаються на aliasing Vite, conditional exports і tree-shaking для видалення коду, призначеного лише для сервера. Хоча aliasing і conditional exports вже застосовані, деякі утиліти на основі Node все ще присутні в пакетах на кшталт `@intlayer/core` на цьому етапі (хоча вони ніколи не імпортуються на клієнті). Оскільки tree-shaking ще не відбувся, ці функції все ще парсяться Babel, і `vite-env-only` виявляє їхні імпорти `node:` та породжує false positive — хоча вони коректно очищуються з фінального клієнтського бандлу.
+
+## Як виправити / обійти
+
+### Рекомендовано: Видалити `vite-env-only`
+
+Просто видаліть цей плагін. У багатьох випадках він не потрібен — Vite вже обробляє розрізнення імпортів для клієнта та сервера через власний механізм резолюції.
+
+Це виправляє хибну відмову через `node:fs` без змін в Intlayer.
+
+### Натомість перевірте фінальну збірку
+
+Якщо ви все ще хочете переконатися, що в клієнтському бандлі немає вбудованих модулів Node, робіть це **після збірки**, наприклад:
+
+```bash
+pnpm build
+grep -R "node:" dist/
+```
+
+Якщо результатів немає, ваші клієнтські бандли чисті.
+
+## Підсумок
+
+- `vite-env-only` може видавати помилку на `node:fs`, оскільки перевіряє занадто рано.
+- Vite + Intlayer + конвенції server modules у React-Router зазвичай правильно видаляють посилання, призначені тільки для сервера.
+- Видалення плагіна або перевірка _фінального виводу_ зазвичай є найкращим рішенням.

package/frequent_questions/uk/esbuild_error.md

@@ -0,0 +1,29 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Помилка ESBuild
+description: Дізнайтеся, як виправляти помилки ESBuild.
+keywords:
+  - esbuild
+  - error
+  - intlayer
+  - plugin
+  - framework
+  - next.js
+  - vite
+  - react-native
+  - lynx
+slugs:
+  - frequent-questions
+  - esbuild-error
+---
+
+# Помилка ESBuild
+
+Якщо під час збірки ви стикаєтеся з помилкою ESBuild, швидше за все плагін Intlayer налаштовано неправильно.
+
+ESBuild відповідає за читання файлів декларації контенту (`.content.{ts,js,mjs,cjs,json}`) та генерацію відповідних словників у папці `.intlayer/dictionary`. А також за читання файлу конфігурації (`intlayer.config.ts`).
+
+Intlayer надає плагіни для інтеграції з вашими бандлерами. Це призначено для створення псевдонімів (alias) для компонентів, які мають виконуватися лише на сервері.
+
+Якщо ви використовуєте фреймворк, такий як Next.js (Webpack / Turbopack), Vite, React Native, Lynx тощо, Intlayer надає плагін, який можна використати для інтеграції Intlayer у ваш застосунок. Тому зверніться до специфічної документації вашого фреймворка, щоб дізнатися, як інтегрувати плагін.

package/frequent_questions/uk/get_locale_cookie.md

@@ -0,0 +1,142 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Як отримати локаль із cookie / заголовків?
+description: Дізнайтеся, як отримати локаль із cookie / заголовків.
+keywords:
+  - cookie
+  - headers
+  - intlayer
+  - locale
+  - hook
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - frequent-questions
+  - get-locale-cookie
+---
+
+# Як отримати локаль із cookie / заголовків
+
+## Використання хуків (рекомендується)
+
+У більшості випадків рекомендовано отримувати поточну локаль за допомогою хука `useLocale`, оскільки вона вирішується автоматично. Це працює аналогічно до `useLocale` composable у Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// or import { useLocale } from "react-intlayer";
+// або імпортуйте { useLocale } з "vue-intlayer";
+
+// Використання на клієнті
+const { locale } = useLocale();
+```
+
+Для серверних компонентів ви можете імпортувати його з:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+Також існує хук `useLocaleCookie`, який лише повертає значення cookie.
+
+## Ручна конфігурація cookie
+
+Ви можете задати власну назву cookie, наприклад
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // за замовчуванням 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+отримати його наступним чином
+
+### На стороні клієнта
+
+```ts
+// Використання імені cookie за замовчуванням
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// Використання користувацького імені cookie
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### На сервері (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// Використання імені cookie за замовчуванням
+const locale = cookies().get("intlayer-locale")?.value;
+
+// Використання користувацького імені cookie
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### Якщо локаль ще не встановлена
+
+Локаль встановлюється в cookie лише після того, як користувач явно вибере локаль. За замовчуванням для нових відвідувачів локаль визначається за полями заголовків.
+
+Ви можете визначити бажану локаль користувача з заголовків запиту. Ось приклад, як це можна реалізувати:
+
+```ts
+/**
+ * Визначає локаль з заголовків запиту
+ *
+ * Заголовок accept-language є найважливішим для визначення локалі.
+ * Він містить список кодів мов зі значеннями якості (q-values), які вказують
+ * пріоритетні мови користувача в порядку переваги.
+ *
+ * Приклад: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US — основна мова (q=1.0 мається на увазі)
+ * - en — другий вибір (q=0.9)
+ * - fr — третій вибір (q=0.8)
+ * - es — четвертий вибір (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * Приклад negotiator headers, які зазвичай надсилають браузери
+ * Ці заголовки допомагають визначити переважну мову користувача
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// Приклад використання:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/uk/intlayer_command_undefined.md

@@ -0,0 +1,155 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Команда intlayer не визначена
+description: Дізнайтеся, як виправити помилку «команда intlayer не визначена».
+keywords:
+  - intlayer
+  - command
+  - undefined
+  - error
+  - vscode
+  - extension
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - frequent-questions
+  - intlayer-command-undefined
+---
+
+# Команда intlayer не визначена
+
+## Огляд
+
+Intlayer CLI надає зручний спосіб керування вашим вмістом intlayer, включно зі збіркою словників, відправкою перекладів та іншим. Однак він не є обов'язковим для роботи вашого проєкту. Якщо ви використовуєте bundler-плагін (наприклад, `withIntlayer()` для Next.js або `intlayer()` для Vite), Intlayer автоматично збирає словники під час збірки додатку або запуску dev-сервера. У режимі розробки він також відслідковує зміни та автоматично перебудовує файли декларацій вмісту.
+
+Ви можете отримати доступ до команд intlayer різними способами:
+
+- Використовуючи CLI-команду `intlayer` безпосередньо
+- Використовуючи [розширення VSCode](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/vs_code_extension.md)
+- Використовуючи SDK `@intlayer/cli`
+
+## Проблема
+
+Коли ви намагаєтеся використати команду `intlayer`, ви можете зіткнутися з цією помилкою:
+
+```bash
+'intlayer' is not recognized as an internal or external command,
+operable program or batch file.
+```
+
+## Рішення
+
+Спробуйте ці рішення в порядку:
+
+1. **Перевірте, що команда встановлена**
+
+```bash
+npx intlayer -h
+```
+
+Очікуваний вивід:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            output the version number
+    -h, --help               display help for command
+
+Commands:
+    dictionary|dictionaries  Dictionaries operations
+    configuration|config     Configuration operations
+    help [command]           display help for command
+```
+
+2. **Встановіть пакет intlayer-cli глобально**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> Це не має бути необхідним, якщо ви вже встановили пакет `intlayer`
+
+3. **Встановіть пакет глобально**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Перезапустіть термінал**
+   Іноді потрібно перезапустити термінал, щоб він розпізнав нові команди.
+
+5. **Очистіть і перевстановіть**
+   Якщо наведені вище рішення не допомогли:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Перевірте файли встановлення**
+   Якщо проблема зберігається, перевірте, що існують такі файли:
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (має містити поле `bin`, що посилається на `./dist/cjs/cli.cjs`)
+
+7. **Перевірте змінну середовища PATH**
+   Переконайтеся, що директорія глобальних bin-файлів npm присутня у вашому PATH:
+
+```bash
+# Для Unix-подібних систем (macOS/Linux)
+echo $PATH
+# Має містити щось на кшталт /usr/local/bin або ~/.npm-global/bin
+
+# Для Windows
+echo %PATH%
+# Має містити каталог глобальних бінарних файлів npm
+```
+
+8. **Use npx with full path**
+   If the command is still not found, try using npx with the full path:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Check for conflicting installations**
+
+```bash
+# Перелічіть усі глобально встановлені пакети
+npm list -g --depth=0
+
+# Видаліть будь-які конфліктні глобальні встановлення
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Потім перевстановіть
+npm install -g intlayer
+```
+
+10. **Verify Node.js and npm versions**
+    Make sure you're using compatible versions:
+
+```bash
+node --version
+npm --version
+```
+
+    If you're using an outdated version, consider updating Node.js and npm.
+
+11. **Перевірте проблеми з дозволами**
+    Якщо ви отримуєте помилки доступу:
+
+    ```bash
+    # Для Unix-подібних систем
+    sudo npm install -g intlayer
+
+    # Або змініть каталог за замовчуванням для npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Додайте в ваш ~/.profile або ~/.bashrc:
+    export PATH=~/.npm-global/bin:$PATH
+    ```

package/frequent_questions/uk/locale_incorect_in_url.md

@@ -0,0 +1,73 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Некоректна локаль, отримана з URL
+description: Дізнайтеся, як виправити некоректну локаль, отриману з URL.
+keywords:
+  - локаль
+  - url
+  - intlayer
+  - next.js
+  - vite
+  - фреймворк
+  - middleware
+  - конфігурація
+  - prefixDefault
+  - noPrefix
+slugs:
+  - frequent-questions
+  - locale-incorect-in-url
+---
+
+# Некоректна локаль, отримана з URL
+
+## Опис проблеми
+
+Коли ви намагаєтеся отримати параметр locale з URL, ви можете зіткнутися з проблемою, коли значення локалі некоректне:
+
+```js
+const { locale } = await params;
+console.log(locale); // повертає "about" замість очікуваної локалі
+```
+
+## Рішення
+
+### 1. Перевірте структуру файлів
+
+Переконайтеся, що шлях у app router вашого Next.js відповідає цій структурі:
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. Перевірте конфігурацію middleware
+
+Проблема часто виникає, коли middleware відсутній або не спрацьовує. Файл middleware має знаходитись за шляхом:
+
+```bash
+src/middleware.ts
+```
+
+Цей middleware відповідає за переписування маршрутів, коли `prefixDefault` встановлено в `false`. Наприклад, він переписує `/en/about` на `/about`.
+
+### 3. Шаблони URL залежно від конфігурації
+
+#### Конфігурація за замовчуванням (`prefixDefault: false`, `noPrefix: false`)
+
+- Англійська: `/about`
+- Французька: `/fr/about`
+- Іспанська: `/es/about`
+
+#### Якщо `prefixDefault: true`
+
+- Англійська: `/en/about`
+- Французька: `/fr/about`
+- Іспанська: `/es/about`
+
+#### Якщо `noPrefix: true`
+
+- Англійська: `/about`
+- Французька: `/about`
+- Іспанська: `/about`
+
+Для докладнішої інформації про ці параметри конфігурації перегляньте [Документацію з конфігурації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md).

package/frequent_questions/uk/package_version_error.md

@@ -0,0 +1,181 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Отримую помилку, пов'язану з підпакетами `@intlayer/*`
+description: Виправлення помилки, пов'язаної з підпакетами @intlayer/*.
+keywords:
+  - @intlayer/*
+  - підпакети
+  - intlayer
+slugs:
+  - frequent-questions
+  - package-version-error
+---
+
+# Отримую помилку, пов'язану з підпакетами `@intlayer/*`
+
+Ця проблема зазвичай виникає після оновлення пакетів Intlayer.
+
+Приклад повідомлення про помилку:
+
+```bash
+Error: Cannot find module '@intlayer/types'
+```
+
+```bash
+TypeError: (0 , __intlayer_config_client.colorize) is not a function
+
+at import { colorize } from '@intlayer/config';
+```
+
+```bash
+✖ ERROR  No matching export in "node_modules/@intlayer/config/dist/esm/client.mjs" for import "clearModuleCache"
+
+node_modules/@intlayer/unmerged-dictionaries-entry/dist/esm/index.mjs:3:9:
+3 | import { clearModuleCache, configESMxCJSRequire } from "@intlayer/config";
+  |          ~~~~~~~~~~~~~~~~
+
+✖ ERROR  No matching export in "node_modules/@intlayer/config/dist/esm/client.mjs" for import "configESMxCJSRequire"
+
+node_modules/@intlayer/unmerged-dictionaries-entry/dist/esm/index.mjs:3:27:
+3 | import { clearModuleCache, configESMxCJSRequire } from "@intlayer/config";
+  |                            ~~~~~~~~~~~~~~~~~~~~
+```
+
+## Причина
+
+Базові пакети, такі як `intlayer`, `react-intlayer`, `react-native-intlayer`, `vue-intlayer`, повторно використовують ті самі суб-пакети `@intlayer/config`, `@intlayer/core`, `@intlayer/types`, щоб уникнути дублювання коду.
+
+Між двома версіями експорти підпакетів не обов'язково збігаються. Щоб зменшити цю проблему, intlayer прив'язує версії підпакетів до версії головного пакета.
+
+> Наприклад: `intlayer@1.0.0` використовує `@intlayer/config@1.0.0`, `@intlayer/core@1.0.0`, `@intlayer/types@1.0.0`
+
+> (За винятком `@intlayer/swc`), підпакети `@intlayer/*` не призначені для прямого використання. Тому рекомендується не встановлювати їх безпосередньо.
+
+## Вирішення
+
+1. Переконайтеся, що версії головного пакета та підпакетів однакові.
+
+```json5
+{
+  "dependencies": {
+    "intlayer": "7.0.1",
+    "react-intlayer": "7.0.0", // Неправильна версія, має бути 7.0.1
+  },
+  "devDependencies": {
+    "intlayer-editor": "7.0.1",
+  },
+}
+```
+
+2. Спробуйте видалити lockfile та папку node_modules і перевстановити залежності.
+
+Інколи пакетний менеджер зберігає стару версію sub-packages у lockfile або в кеші. Щоб виправити це, можна спробувати видалити lockfile та папку node_modules і перевстановити залежності.
+
+```bash
+rm -rf package-lock.json node_modules
+
+npm install # або yarn install або pnpm install або bun pm install
+```
+
+3. Перевірте версії локальних залежностей
+
+Може статися, що ваш пакетний менеджер зберігає стару версію sub-packages у lockfile або в кеші.
+
+Приклад `intlayer@7.0.0` > `@intlayer/config@7.0.0` > `@intlayer/dictionary-entry@6.0.0`.
+
+Щоб виявити невідповідність між версіями локальних залежностей і версіями sub-packages, ви можете використати наступну команду:
+
+```bash
+npm list --depth=3 | grep intlayer
+```
+
+```bash
+yarn list --depth=3 | grep intlayer
+```
+
+```bash
+pnpm list --depth=3 | grep intlayer
+```
+
+```bash
+bun pm ls --depth=3 | grep intlayer
+```
+
+> На Windows замініть `| grep intlayer` на `| findstr intlayer` або використайте PowerShell з `Select-String -Pattern "intlayer"`.
+
+4. Перевірте глобальну інсталяцію
+
+Ми рекомендуємо встановити `intlayer` або `intlayer-cli` глобально, щоб мати доступ до CLI-команд. Якщо глобальна версія відрізняється від локальної версії, пакетний менеджер може обрати невірну версію.
+
+**Перевірити, чи пакет встановлено глобально**
+
+```bash
+npm list -g --depth=3 | grep intlayer
+```
+
+```bash
+yarn global list --depth=3 | grep intlayer
+```
+
+```bash
+pnpm list -g --depth=3 | grep intlayer
+```
+
+```bash
+bun pm ls -g --depth=3 | grep intlayer
+```
+
+> На Windows замініть `| grep intlayer` на `| findstr intlayer` або використовуйте PowerShell з `Select-String -Pattern "intlayer"`.
+
+**Виправте потенційні конфлікти глобальних залежностей**
+
+```bash
+npm uninstall -g intlayer intlayer-cli
+```
+
+```bash
+yarn global remove intlayer intlayer-cli
+```
+
+```bash
+pnpm remove -g intlayer intlayer-cli
+```
+
+```bash
+bun pm rm -g intlayer intlayer-cli
+```
+
+5. Спробуйте очистити кеш
+
+У деяких середовищах, таких як Docker, GitHub Actions або хостинг-платформи на зразок Vercel, може бути задіяний кеш. Спробуйте очистити кеш і повторити встановлення.
+
+Ви також можете очистити кеш вашого пакетного менеджера за допомогою наступних команд:
+
+```bash
+npm cache clean --force
+```
+
+```bash
+yarn cache clean
+```
+
+```bash
+pnpm cache clean
+```
+
+```bash
+bun pm cache clean
+```
+
+6. Спробуйте видалити папку `.intlayer`
+
+Intlayer кешує зібрану версію самої себе в папці `.intlayer/cache`.
+
+Цей кеш може бути пошкоджений, якщо версія intlayer відрізняється від версії, збереженої в кеші.
+
+Ви можете спробувати видалити папку `.intlayer` і повторити збірку.
+
+```bash
+rm -rf .intlayer
+```