@intlayer/docs 7.5.11 → 7.5.13

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

@@ -0,0 +1,77 @@
+---
+createdAt: 2026-01-11
+updatedAt: 2026-01-11
+title: "`vite-env-only` & Intlayer – yanlış pozitif `node:fs` reddedildi hatası"
+description: "vite-env-only'nin Intlayer + React-Router + Vite ile `node:fs` importunu neden reddettiğini ve yapılması gerekenleri."
+keywords:
+  - intlayer
+  - vite
+  - react-router
+  - vite-env-only
+  - node:fs
+  - import reddedildi
+  - alias
+  - client bundle
+slugs:
+  - frequent-questions
+  - vite-env-only-node-fs-false-positive
+---
+
+# vite-env-only Intlayer ile `node:fs`'i reddediyor
+
+Eğer **vite-env-only** eklentisini kullandıysanız (eski React-Router v7 önerilerinde belirtildiği gibi) ve şu hatayı görüyorsanız:
+
+```bash
+
+Error: [vite-env-only] Import denied
+
+* Denied by specifier pattern: /^node:/
+* Importer: index.html
+* Import: "node:fs"
+
+```
+
+…istemci paketinizde **`node:fs` olmasa bile**, bu bir **yanlış pozitif**.
+
+## Buna ne sebep oluyor
+
+`vite-env-only`, Vite grafik çözümlemesinin **erken aşamasında** Babel tabanlı bir kontrol çalıştırır, _şundan önce_:
+
+- aliasing (Intlayer’ın tarayıcı vs node eşlemeleri dahil),
+- kullanılmayan kodun kaldırılması (dead-code elimination),
+- SSR ile istemci çözümlemesi,
+- React-Router gibi sanal modüller.
+
+Intlayer paketleri hem Node hem tarayıcı üzerinde çalışabilecek kod içerir. Bir _ara_ aşamada, `node:fs` gibi bir Node yerleşiği grafikte Vite bunun istemci derlemesinden kaldırmasından **önce** görünebilir. `vite-env-only` bunu görür ve nihai paket bunu içermese bile hemen hata verir.
+
+## React-Router ve Sunucu Modülleri
+
+React-Router dokümantasyonunda **sunucu modülü konvansiyonları** ile ilgili olarak
+(https://reactrouter.com/api/framework-conventions/server-modules), ekip, sunucuya özel importların istemci paketine sızmasını önlemek için **açıkça `vite-env-only` kullanmayı önerir**.
+
+Ancak bu konvansiyonlar, sunucuya özel kodu kaldırmak için Vite’in aliasing’ine, conditional exports'ına ve tree-shaking’ine dayanır. Alias’lama ve conditional exports zaten uygulanmış olsa da, bazı Node tabanlı yardımcılar bu aşamada `@intlayer/core` gibi paketlerde hâlâ mevcut olabilir (istemcide hiç import edilmemiş olsalar bile). Çünkü tree-shaking henüz çalışmadığından, bu fonksiyonlar hâlâ Babel tarafından parse edilir ve `vite-env-only` onların `node:` importlarını tespit edip yanlış pozitif bir hata verir — oysa bunlar nihai istemci paketinden doğru şekilde temizlenir.
+
+## Nasıl düzeltilecek / geçici çözümler
+
+### Önerilen: `vite-env-only`'ı kaldırın
+
+Eklentiyi basitçe kaldırın. Birçok durumda buna gerek yok — Vite kendi çözümlemesiyle istemci ve sunucu importlarını zaten yönetir.
+
+Bu, Intlayer'da değişiklik yapmadan yanlış `node:fs` reddini düzeltir.
+
+### Bunun yerine son yapıyı doğrulayın
+
+İstemci paketlerinde Node yerleşiklerinin bulunmadığından hâlâ emin olmak istiyorsanız, bunu **build sonrası** yapın, örn:
+
+```bash
+pnpm build
+grep -R "node:" dist/
+```
+
+Eğer sonuç yoksa, istemci bundle'larınız temizdir.
+
+## Özet
+
+- `vite-env-only` çok erken kontrol ettiği için `node:fs` üzerinde hata verebilir.
+- Vite + Intlayer + React-Router'ın server modules konvansiyonları genellikle yalnızca sunucuya ait referansları doğru şekilde kaldırır.
+- Eklentiyi kaldırmak veya _nihai çıktıyı_ doğrulamak genellikle en iyi çözümdür.

package/frequent_questions/uk/SSR_Next_no_[locale].md

@@ -0,0 +1,104 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Чи можна використовувати Intlayer з Next.js без `[locale]` у шляху сторінки?
+description: Дізнайтеся, як використовувати Intlayer з Next.js без `[locale]` у шляху сторінки.
+keywords:
+  - locale
+  - path
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuration
+  - prefixDefault
+  - noPrefix
+slugs:
+  - frequent-questions
+  - next-no-locale-path
+---
+
+# Чи можна використовувати Intlayer з Next.js без `[locale]` у шляху сторінки?
+
+Так — можна використовувати Intlayer з Next.js без `[locale]` у шляху сторінки. Однак цього не рекомендується робити, оскільки розділення сторінок по локалях дозволяє підвищити видимість за більшою кількістю ключових слів у пошукових системах. Крім того, це може вплинути на ваш SSR.
+
+Якщо ви хочете це зробити, дотримуйтеся тих самих кроків, що описані в керівництві [Intlayer with Next.js](https://intlayer.org/doc/environment/nextjs),
+
+- без `src/middleware.ts`
+- без `generateStaticParams`
+
+```tsx fileName="src/app/layout.tsx"
+import type { FC, PropsWithChildren } from "react";
+
+const LocaleLayout: FC<PropsWithChildren> = ({ children }) => (
+  <html lang={undefined} dir={undefined}>
+    <body className={inter.className}>{children}</body>
+  </html>
+);
+
+export default LocaleLayout;
+```
+
+```tsx fileName="src/app/page.tsx"
+import type { FC } from "react";
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { PageContent } from "@components/pageContent";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC = () => {
+  return (
+    <IntlayerServerProvider>
+      <PageContent />
+      <ServerComponentExample />
+
+      <IntlayerClientProvider>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```tsx fileName="src/component/pageContent.ts"
+"use client";
+
+import { type FC } from "react";
+import { useIntlayer } from "next-intlayer";
+import { useHTMLLanguage } from "@hooks/htmlTextDir";
+
+const PageContent: FC = () => {
+  useHTMLLanguage();
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/hooks/htmlTextDir.ts"
+"use client";
+
+import { useEffect } from "react";
+import { getHTMLTextDir } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const useHTMLLanguage = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    if (!document) return;
+
+    document.documentElement.lang = locale;
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```

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. **Простіше обслуговування**: Розгортання для кожної мови незалежне