@intlayer/docs 7.5.12 → 7.5.13

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
+```

package/frequent_questions/uk/static_rendering.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Статичний vs динамічний рендеринг з i18n у Next.js
+description: Дізнайтеся, як використовувати статичний та динамічний рендеринг з i18n у Next.js.
+keywords:
+  - статичний
+  - динамічний
+  - рендеринг
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - фреймворк
+  - middleware
+  - конфігурація
+slugs:
+  - frequent-questions
+  - static-rendering
+---
+
+# Статичний vs динамічний рендеринг з i18n у Next.js
+
+## Проблема з **next-intl**
+
+- **Що відбувається?**
+  Коли ви використовуєте `useTranslations`, `getTranslations`, або будь-який хелпер next-intl _всередині Server Component_ в застосунку з i18n-маршрутизацією (`/en/…`, `/fr/…`), Next.js позначає весь маршрут як **dynamic**. ([Next Intl][1])
+
+- **Чому?**
+  next-intl визначає поточну локаль з заголовка, доступного лише в запиті (`x-next-intl-locale`) через `headers()`. Оскільки `headers()` — це **динамічний API**, будь-який компонент, який до нього звертається, втрачає статичну оптимізацію. ([Next Intl][1], [Next.js][2])
+
+- **Офіційне рішення (boilerplate)**
+  1. Експортуйте `generateStaticParams` для кожної підтримуваної локалі.
+  2. Викликайте `setRequestLocale(locale)` у **кожному** layout/page _перед_ тим, як викликати `useTranslations`. ([Next Intl][1])
+     Це усуває залежність від заголовка, але додає додатковий код для підтримки та використовує нестабільний API у продакшені.
+
+## Як **intlayer** обходить проблему
+
+**Дизайн-рішення**
+
+1. **Тільки параметр маршруту (route-param only)** – локаль береться з сегмента URL `[locale]`, який Next.js вже передає кожній сторінці.
+2. **Бандли на етапі компіляції** – Переклади імпортуються як звичайні ES-модулі, тож вони піддаються tree-shaking і вбудовуються під час збірки.
+3. **Без динамічних API** – `useT()` читає з React context, а не з `headers()` або `cookies()`.
+4. **Жодної додаткової конфігурації** – Як тільки ваші сторінки розміщені під `app/[locale]/`, Next.js автоматично генерує по одному HTML‑файлу на кожну локаль.

package/frequent_questions/uk/translated_path_url.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Чи можна перекласти шлях URL?
+description: Дізнайтеся, як перекласти шлях URL.
+keywords:
+  - array
+  - content
+  - declaration
+  - intlayer
+  - middleware
+  - proxy
+  - rewrite
+  - prefix
+  - locale
+  - url
+slugs:
+  - frequent-questions
+  - translated-path-url
+---
+
+# Чи можливо перекласти URL наступним чином:
+
+```bash
+en -> /product (без префікса) або /en/product (з префіксом)
+fr -> /fr/produit
+es -> /es/producto
+```
+
+На жаль, Intlayer не дозволяє перекладати URL так, як зазначено вище. Щоб досягти цього, ви повинні використовувати власний middleware або proxy для перезапису (rewrite) URL.
+
+Але ви можете використовувати функцію `getMultilingualUrl`, щоб вставити префікс у URL для заданої локалі.
+
+```ts
+import { getMultilingualUrl, Locales } from "intlayer";
+
+const url = getMultilingualUrl("/product");
+
+/**
+ * en -> /product (без префікса) або /en/product (з префіксом)
+ * fr -> /fr/product
+ * es -> /es/product
+ */
+console.log(url);
+```
+
+Або `getLocalizedUrl`
+
+```ts
+import { getLocalizedUrl, Locales } from "intlayer";
+
+const url = getLocalizedUrl("/product", Locales.FRENCH);
+
+console.log(url); // виведе: /fr/product
+```

package/frequent_questions/uk/unknown_command.md

@@ -0,0 +1,97 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Невідома команда
+description: Дізнайтеся, як виправити помилку невідомої команди.
+keywords:
+  - невідома
+  - команда
+  - помилка
+  - intlayer
+  - fill
+  - build
+  - verbose
+  - термінал
+  - перезапуск
+  - локально
+slugs:
+  - frequent-questions
+  - unknown-command
+---
+
+# помилка: невідома команда fill / build / тощо
+
+Якщо `npx intlayer fill --verbose` видає:
+
+```
+error: unknown command 'fill'
+```
+
+але ви впевнені, що команда `fill` _повинна_ існувати, ось кроки для вирішення:
+
+## 1. **Переконайтеся, що ви використовуєте найновішу версію**
+
+Запустіть:
+
+```bash
+npx intlayer --version                  # поточна локальна версія intlayer
+npx intlayer@latest --version           # остання доступна версія intlayer
+```
+
+Це змушує `npx` завантажити найновішу версію. Потім спробуйте ще раз:
+
+```bash
+npx intlayer@latest build --verbose
+```
+
+## 2. **Перевірте, чи команда зареєстрована**
+
+Ви можете перевірити за допомогою:
+
+```bash
+npx intlayer --help                     # надає інформацію про команди
+```
+
+Перевірте, чи з'являється команда у списку команд.
+
+Перейдіть у репозиторій та підтвердьте, що ваша команда експортується й зареєстрована в точці входу CLI. Intlayer використовує `commander` як фреймворк.
+
+Код, що стосується CLI:
+https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/cli/src/cli.ts
+
+## 4. **Перезапустіть термінал**
+
+Іноді потрібно перезапустити термінал, щоб він розпізнав нові команди.
+
+## 5. **Якщо ви розробляєте `intlayer`, перебудуйте та підключіть його**
+
+Якщо ви розробляєте `intlayer` локально:
+
+```bash
+# У директорії intlayer
+npm install
+npm run build
+npm link
+```
+
+Потім в іншому терміналі:
+
+```bash
+intlayer fill --verbose
+```
+
+Це використовує локальну версію, над якою ви працюєте.
+
+## 6. **Очистіть кеш npx (якщо ви застрягли на старішій версії)**
+
+```bash
+npx clear-npx-cache
+```
+
+Або вручну видаліть кешовані пакети intlayer:
+
+```bash
+rm -rf ~/.npm/_npx
+```
+
+Перевірте еквівалентні команди, якщо ви використовуєте pnpm, yarn, bun або інший пакетний менеджер

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

@@ -0,0 +1,77 @@
+---
+createdAt: 2026-01-11
+updatedAt: 2026-01-11
+title: `vite-env-only` & Intlayer – lỗi từ chối `node:fs` dương tính giả
+description: Tại sao vite-env-only báo một import `node:fs` bị từ chối khi dùng Intlayer + React-Router + Vite và phải làm gì.
+keywords:
+  - intlayer
+  - vite
+  - react-router
+  - vite-env-only
+  - node:fs
+  - import bị từ chối
+  - alias
+  - bundle phía client
+slugs:
+  - frequent-questions
+  - vite-env-only-node-fs-false-positive
+---
+
+# vite-env-only từ chối `node:fs` với Intlayer
+
+Nếu bạn đã sử dụng plugin **vite-env-only** (như được đề cập trong các gợi ý React-Router v7 cũ hơn) và thấy:
+
+```bash
+
+Error: [vite-env-only] Import denied
+
+* Denied by specifier pattern: /^node:/
+* Importer: index.html
+* Import: "node:fs"
+
+```
+
+…mặc dù **không có `node:fs` trong bundle phía client của bạn**, đây là một **false positive (dương tính giả)**.
+
+## Nguyên nhân gây ra
+
+`vite-env-only` chạy một kiểm tra dựa trên Babel **rất sớm trong quá trình phân giải graph của Vite**, _trước khi_:
+
+- aliasing (bao gồm ánh xạ browser vs node của Intlayer),
+- dead-code elimination,
+- SSR vs client resolution,
+- các module ảo như của React-Router.
+
+Các package của Intlayer chứa mã có thể chạy trên cả Node và trình duyệt. Ở một giai đoạn _trung gian_, một builtin của Node như `node:fs` có thể xuất hiện trong graph **trước khi** Vite loại bỏ nó khỏi build phía client. `vite-env-only` nhìn thấy điều đó và báo lỗi ngay lập tức, mặc dù bundle cuối cùng không chứa nó.
+
+## React-Router và Server Modules
+
+Trong tài liệu của React-Router về **server module conventions**
+(https://reactrouter.com/api/framework-conventions/server-modules), nhóm **rõ ràng khuyến nghị sử dụng `vite-env-only`** để ngăn các import chỉ dành cho server bị rò rỉ vào bundle phía client.
+
+Tuy nhiên, những quy ước đó dựa vào aliasing của Vite, conditional exports và tree-shaking để loại bỏ mã chỉ dành cho server. Trong khi aliasing và conditional exports đã được áp dụng, một số tiện ích dựa trên Node vẫn còn xuất hiện trong các package như `@intlayer/core` ở giai đoạn đó (mặc dù chúng không bao giờ được import vào client). Vì tree-shaking chưa chạy, các hàm đó vẫn bị Babel phân tích cú pháp, và `vite-env-only` phát hiện các import `node:` của chúng và báo dương tính giả — mặc dù chúng đã được loại bỏ chính xác khỏi bundle cuối cùng của client.
+
+## Cách khắc phục / giải pháp tạm thời
+
+### Khuyến nghị: Gỡ bỏ `vite-env-only`
+
+Chỉ cần gỡ plugin. Trong nhiều trường hợp bạn không cần nó — Vite đã xử lý việc phân biệt imports client và server thông qua cơ chế resolution của nó.
+
+Điều này sửa lỗi báo sai `node:fs` mà không cần thay đổi Intlayer.
+
+### Thay vào đó, kiểm tra bản build cuối cùng
+
+Nếu bạn vẫn muốn đảm bảo không có built-in của Node trong client, hãy làm điều đó **sau khi build**, ví dụ:
+
+```bash
+pnpm build
+grep -R "node:" dist/
+```
+
+Nếu không có kết quả, các bundle client của bạn sạch.
+
+## Tóm tắt
+
+- `vite-env-only` có thể báo lỗi về `node:fs` vì nó kiểm tra quá sớm.
+- Vite + Intlayer + quy ước server modules của React-Router thường loại bỏ tham chiếu chỉ dành cho server một cách chính xác.
+- Gỡ plugin hoặc kiểm tra _kết quả cuối cùng_ thường là giải pháp tốt nhất.