@intlayer/docs 7.5.12 → 7.5.14

package/frequent_questions/uk/array_as_content_declaration.md

@@ -0,0 +1,72 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Чи можна використовувати масив як декларацію контенту?
+description: Дізнайтеся, як використовувати масив як декларацію контенту.
+keywords:
+  - масив
+  - вміст
+  - оголошення
+  - intlayer
+slugs:
+  - frequent-questions
+  - array-as-content-declaration
+---
+
+# Чи можна використовувати масив як декларацію контенту?
+
+Так — ви можете використовувати масив як декларацію контенту.
+
+```ts
+import { t, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  content: {
+    test: t({
+      uk: ["Тест", "Тест2", "Тест3"],
+      en: ["Test", "Test2", "Test3"],
+      fr: ["Test", "Test2", "Test3"],
+      es: ["Test", "Test2", "Test3"],
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+Далі ви можете використовувати контент ось так:
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+
+const Example = () => {
+  const content = useIntlayer("example");
+
+  return (
+    <div>
+      {content.test.map((item) => (
+        <div key={item.value}>{item}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+```vue
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("example");
+</script>
+
+<template>
+  <div>
+    <div v-for="item in content.test" :key="item.value">
+      {{ item }}
+    </div>
+  </div>
+</template>
+```
+
+.value дозволяє отримати значення контенту, яке не обгорнуте в `IntlayerNode`.

package/frequent_questions/uk/build_dictionaries.md

@@ -0,0 +1,58 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Як згенерувати словники?
+description: Дізнайтеся, як згенерувати словники.
+keywords:
+  - build
+  - словники
+  - intlayer
+  - команда
+  - watch
+  - vscode
+  - плагін
+  - framework
+  - next.js
+  - vite
+slugs:
+  - frequent-questions
+  - build-dictionaries
+---
+
+# Build Dictionaries
+
+## How to Build Dictionaries
+
+Intlayer provides a command-line tool to build dictionaries.
+
+```bash
+npx intlayer dictionaries build
+```
+
+This command:
+
+- Scans all content declaration files (`.content.{ts,tsx,js,mjs,cjs,json,...}`) in your project.
+- Generates dictionaries and stores them in the `.intlayer/dictionary` folder.
+
+### Watch Mode
+
+Якщо ви хочете автоматично оновлювати словники при внесенні змін у файли декларацій контенту, виконайте таку команду:
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+У цьому режимі Intlayer скануватиме та будуватиме словники щоразу, коли вносяться зміни у файли декларацій контенту, і автоматично оновлюватиме папку `.intlayer/dictionary`.
+
+### Використання розширення VSCode
+
+Ви також можете використовувати [розширення Intlayer для VSCode](https://github.com/aymericzip/intlayer/tree/main/docs/uk/vs_code_extension.md), щоб покращити роботу з Intlayer у VSCode.
+
+### Використання плагіна для вашого улюбленого фреймворка
+
+Якщо ви використовуєте фреймворк на кшталт Next.js (Webpack / Turbopack), Vite, React Native, Lynx тощо, Intlayer надає плагін, який ви можете використати для інтеграції Intlayer у ваш додаток.
+
+Intlayer збирає словники перед збіркою вашого додатка.
+Аналогічно, у режимі розробки Intlayer стежитиме за змінами у файлах декларації контенту й автоматично перебудовуватиме словники.
+
+Тому зверніться до документації, специфічної для вашого фреймворку, щоб дізнатися, як інтегрувати плагін.

package/frequent_questions/uk/build_error_CI_CD.md

@@ -0,0 +1,74 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Помилка збірки в CI/CD
+description: Дізнайтеся, як виправити помилки збірки, що виникають у середовищах CI/CD.
+keywords:
+  - build
+  - error
+  - ci
+  - cd
+  - pipeline
+  - intlayer
+  - dictionaries
+  - next.js
+  - prebuild
+  - automation
+slugs:
+  - frequent-questions
+  - build-error-ci-cd
+---
+
+# Помилка під час збірки в CI/CD
+
+Якщо ви отримуєте таку помилку в Next.js:
+
+```text
+Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error
+```
+
+Ось кілька рішень:
+
+## 1. Відсутні словники
+
+Переконайтеся, що dictionaries будуються під час етапу збірки.
+
+Часто збірка працює локально, але не в CI/CD. Причина в тому, що локально каталог `.intlayer` присутній, а в CI/CD його немає, бо він виключений із збірки.
+
+Ви можете виправити це, додавши скрипт prebuild у `package.json` вашого проєкту.
+
+```json5 fileName=package.json
+{
+  // інше ...
+  "scripts": {
+    "prebuild": "npx intlayer dictionaries build", // Виконається перед збіркою
+    "build": "next build",
+  },
+}
+```
+
+> Зауважте, що якщо ви використовуєте функцію `withIntlayer`, або еквівалентний bundler plugin для вашого фреймворку, скрипт prebuild буде виконаний перед збіркою.
+
+## 2. Відсутні змінні середовища під час збірки / виконання
+
+У контейнері або на платформі з автоматичним деплоєм рекомендується виключати файл `.env` з процесу збірки.
+
+```text fileName=".gitignore or .dockerignore"
+# Змінні середовища
+.env
+**/.env
+.env.*
+**/.env.*
+```
+
+Якщо ваші змінні середовища недоступні під час збірки, буде викинута помилка.
+
+```ts
+import { Metadata } from "next";
+
+export const generateMetadata = async ({ params }): Promise<Metadata> => ({
+  metadataBase: new URL(process.env.NEXT_PUBLIC_URL),
+});
+```
+
+Ймовірно, це не пов'язано з Intlayer. Тому перевірте свої змінні середовища під час збірки на вашій CI/CD-платформі.

package/frequent_questions/uk/bun_set_up.md

@@ -0,0 +1,53 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Отримую помилку module not found при використанні bun
+description: Виправлення помилки при використанні bun.
+keywords:
+  - bun
+  - модуль не знайдено
+  - intlayer
+  - конфігурація
+  - пакетний менеджер
+slugs:
+  - frequent-questions
+  - bun-set-up
+---
+
+# Отримую помилку 'module not found' при використанні bun
+
+## Опис проблеми
+
+При використанні bun ви можете зіткнутися з помилкою на кшталт цієї:
+
+```bash
+Cannot find package 'intlayer' from '/workspace/packages/@intlayer/config/dist/cjs/utils/ESMxCJSHelpers.cjs' undefined
+```
+
+## Причина
+
+Intlayer використовує `require` внутрішньо. А bun обмежує область дії функції `require`, через що вона резолвить лише пакети пакета `@intlayer/config`, а не весь проєкт.
+
+## Рішення
+
+### Надайте функцію `require` у конфігурації
+
+```ts
+const config: IntlayerConfig = {
+  build: {
+    require,
+  },
+};
+
+export default config;
+```
+
+```ts fileName="next.config.ts" codeFormat="typescript"
+import { withIntlayer } from "next-intlayer/server";
+
+const configuration = withIntlayer({
+  require,
+});
+
+export default configuration;
+```

package/frequent_questions/uk/customized_locale_list.md

@@ -0,0 +1,64 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Як налаштувати список локалей?
+description: Дізнайтеся, як налаштувати список локалей.
+keywords:
+  - локалі
+  - список
+  - intlayer
+  - конфігурація
+  - availableLocales
+  - defaultLocale
+  - useLocale
+  - hook
+  - локаль
+  - список
+slugs:
+  - frequent-questions
+  - customized-locale-list
+---
+
+# Чи можна заблокувати певну мову, наприклад англійську? Я додаю англійську у свої словники, але поки не хочу, щоб англійська була доступна на сайті
+
+Так, ви можете заблокувати певну мову, наприклад англійську, використавши опцію `availableLocales` у конфігурації Intlayer.
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  locales: [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH],
+  availableLocales: [Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+або
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const locales = [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH];
+
+const config: IntlayerConfig = {
+  locales,
+  availableLocales: locales.filter((locale) => locale !== Locales.ENGLISH),
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+Ця конфігурація змінить типи вашої функції `t()` так, щоб вони включали лише доступні локалі.
+
+Опція availableLocales є необов'язковою — якщо ви її не вкажете, будуть доступні всі локалі.
+
+Увага: усі локалі, включені в опцію `availableLocales`, повинні бути також включені в опцію `locales`.
+
+Зауважте, що якщо ви використовуєте хук `useLocale`, опція `availableLocales` буде використана для встановлення доступу до списку локалей.
+
+```ts
+import { useLocale } from "react-intlayer";
+
+const { availableLocales } = useLocale();
+
+console.log(availableLocales); // Виведе: [Locales.FRENCH, Locales.SPANISH]
+```

package/frequent_questions/uk/domain_routing.md

@@ -0,0 +1,113 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Як налаштувати маршрутизацію на основі домену?
+description: Дізнайтеся, як налаштувати маршрутизацію на основі домену.
+keywords:
+  - домен
+  - маршрутизація
+  - intlayer
+  - конфігурація
+  - middleware
+  - react-router
+  - vue-router
+  - next.js
+  - vite
+  - фреймворк
+slugs:
+  - frequent-questions
+  - domain-routing
+---
+
+# Як налаштувати **маршрутизацію на основі домену** в Intlayer замість шляхів `/[locale]/`?
+
+## Коротка відповідь
+
+Маршрутизація на основі домену простіша за маршрутизацію через шляхи (`example.com/[locale]/`), оскільки ви можете пропустити всю конфігурацію middleware та маршрутизації. Просто розгорніть ваш додаток на кожному мовному домені та встановіть по одній змінній оточення для кожного домену.
+
+## Покроково
+
+1. **Розгорніть додаток окремо для кожного домену** (`example.com`, `exemple.fr`, `ejemplo.es`, …).
+2. Для кожного розгортання встановіть `LOCALE` (та звичайні змінні оточення Intlayer) у локаль, яку має обслуговувати цей домен.
+3. Посилайтеся на цю змінну як `defaultLocale` у вашому `intlayer.config.[ts|js]`.
+
+```ts
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: process.env.LOCALE, // 👈 домен визначає локаль
+  },
+  // ... решта вашої конфігурації
+};
+
+export default config;
+```
+
+Ось і все — те саме працює для **Next.js**, **Vite + React**, **Vite + Vue** тощо.
+
+## Що якщо всі домени вказують на **те саме** розгортання?
+
+Якщо всі домени вказують на той самий бандл застосунку, вам потрібно визначати хост під час виконання та передавати локаль вручну через провайдер.
+
+### Для Next.js
+
+```tsx
+// src/IntlayerProvider.tsx
+import {
+  IntlayerClientProvider,
+  type IntlayerClientProviderProps,
+} from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+import type { FC } from "react";
+
+export const IntlayerProvider: FC<IntlayerClientProviderProps> = ({
+  children,
+  locale,
+}) => {
+  const resolvedLocale = locale ?? getLocaleFromHostname();
+  return (
+    <IntlayerServerProvider locale={resolvedLocale}>
+      <IntlayerClientProvider locale={resolvedLocale}>
+        {children}
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+```
+
+### Для Vue
+
+```ts
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import { router } from "./routes";
+
+const app = createApp(App);
+app.use(router);
+installIntlayer(app, getLocaleFromHostname());
+app.mount("#app");
+```
+
+Замініть `getLocaleFromHostname()` своєю власною логікою визначення локалі.
+
+## Оновіть ваш перемикач локалі
+
+Коли використовується маршрутизація на основі доменів, зміна мови означає перехід на інший домен:
+
+```ts
+const { locale } = useLocale();
+
+function changeLanguage(target: Locale) {
+  window.location.href = domainForLocale[target];
+}
+```
+
+## Переваги маршрутизації на основі доменів
+
+1. **Простіша конфігурація**: Немає потреби налаштовувати `intlayerProxy`, `generateStaticParams`, `react-router` або `vue-router`
+2. **Краще SEO**: Кожна мова має власний домен
+3. **Чистіші URL-адреси**: Немає префікса локалі в шляху
+4. **Простіше обслуговування**: Розгортання для кожної мови незалежне

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