@intlayer/docs 9.0.0-canary.5 → 9.0.0-canary.7

package/docs/uk/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Документація плагина Vite intlayerProxy | vite-intlayer
+description: Middleware локалізації роутингу для серверів dev/preview у Vite та серверного рендерингу (SSR) у продакшені. Обробляє визначення мови, перенаправлення URL та внутрішні перезаписи шляхів.
+keywords:
+  - intlayerProxy
+  - vite
+  - плагін
+  - middleware
+  - локаль
+  - роутинг
+  - інтернаціоналізація
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Параметр configOptions об'єднано в один об'єкт налаштувань; проксі вбудовано в intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` — це плагін Vite, який реєструє проміжне програмне забезпечення (middleware) локалізації роутингу для **будь-якого середовища**: dev-сервера, preview-сервера та продакшен SSR (Nitro / TanStack Start).
+
+> **Починаючи з Intlayer v9**, `intlayerProxy` автоматично включається в основний плагін [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vite-intlayer/intlayer.md) і активований за замовчуванням за допомогою налаштування `routing.enableProxy: true`. Вам потрібно реєструвати його окремо лише в тому випадку, якщо вам потрібен низькорівневий контроль або якщо ви використовуєте його за межами стандартної конфігурації `intlayer()`.
+
+## Використання
+
+### У складі `intlayer()` (рекомендовано, v9+)
+
+Передайте параметри `proxy` в основний плагін замість окремої реєстрації `intlayerProxy`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### Окремо (за необхідності)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Параметри
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+Усі параметри є необов'язковими і передаються у вигляді єдиного об'єкта:
+
+| Параметр        | Тип                                 | Опис                                                                                                                                                                                        |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Предикат, який виключає запити з локалізації роутингу. Поверніть `true`, щоб пропустити запит (наприклад, для роутів API, health check-ів).                                                 |
+| `configOptions` | `GetConfigurationOptions`           | Перевизначення конфігурації Intlayer, що передаються в `getConfiguration()`. Використовуйте, коли вам потрібно, щоб проксі читав конкретний конфігураційний файл або перевизначав значення. |
+
+### Приклад
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` створює незалежний від фреймворку Node.js middleware `(req, res, next)`, який містить всю логіку локалізації роутингу. Це корисно в середовищах, де API плагінів Vite недоступний (наприклад, на звичайному сервері Node.js або в кастомному модулі Nitro).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### Продакшен SSR (TanStack Start / Nitro через h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## Поведінка роутингу
+
+Цей middleware дублює логіку роутингу з middleware `next-intlayer` і підтримує всі режими роутингу Intlayer.
+
+### Режими роутингу
+
+| Режим           | URL видно в браузері     | Поведінка                                                                                                                      |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`        | `/uk/about`              | За замовчуванням. Префікс мови в URL. Мова за замовчуванням перенаправляє на URL без префікса, якщо не активний `prefix-all`.  |
+| `prefix-all`    | `/en/about`, `/uk/about` | Усі мови (включаючи мову за замовчуванням) завжди мають префікс в URL.                                                         |
+| `no-prefix`     | `/about`                 | Немає мови в URL. Мова зберігається тільки в cookies; перезапис URL відбувається на внутрішньому рівні.                        |
+| `search-params` | `/about?locale=uk`       | Мова передається як query-параметр. Перенаправляє для додавання/оновлення параметра `locale`, якщо він відсутній або застарів. |
+
+### Пріоритет визначення
+
+1. Префікс шляху URL (наприклад, `/uk/about` → `uk`).
+2. Значення в cookie / localStorage (`intlayer-locale`).
+3. Заголовок `Accept-Language`.
+4. `defaultLocale` з конфігурації.
+
+### Автоматичний обхід (Bypass)
+
+Цей middleware завжди пропускає наступні запити безпосередньо без обробки локалі:
+
+- Запити, що відповідають предикату `ignore`.
+- `/node_modules/**`
+- `/@**` — внутрішні запити Vite (`@vite/`, `@fs/`, `@id/` тощо).
+- `/_**` — внутрішні запити сервера (`__vite_ping`, `__manifest` тощо).
+- Запити, шлях яких закінчується розширенням файлу (статичні файли). Якщо в шляху статичного файлу присутній мовний префікс (наприклад, `/uk/logo.png`), він видаляється, щоб файл міг бути відданий коректно.
+
+### Роутинг по доменах
+
+Коли у вашій конфігурації Intlayer налаштовано параметр `routing.domains`, цей middleware обробляє роутинг мов між різними доменами:
+
+- Запит для `/zh/about` на домені `intlayer.org` перенаправляється на `https://intlayer.zh/about`, коли `domains.zh = "intlayer.zh"`.
+- Запит до `intlayer.zh/about` внутрішньо переписується в `/zh/about`, щоб заповнився параметр маршруту `[locale]`.
+
+### Захист від нескінченного редиректу
+
+Цей middleware відстежує кількість перенаправлень для пари `originalUrl → newUrl` у рухомому 2-секундному вікні. Більше 10 перенаправлень у цьому вікні повертають помилку `500` із докладним описом замість нескінченного циклу.
+
+## Nitro / SSR у продакшені (автоматичне впровадження, v9+)
+
+Коли `intlayerProxy` використовується як плагін Vite, він містить властивість `.nitro`. Плагін збірки `nitro/vite` зчитує цю властивість і поміщає її в `nitroConfig.modules`, завдяки чому `intlayerNitroHandler` реєструється як middleware сервера Nitro автоматично — для продакшен SSR не потрібне ручне налаштування.
+
+Обробник Nitro використовує модель подій Web Fetch API h3 v2 (а не `fromNodeMiddleware`), тому він сумісний з усіма пресетами Nitro: Node, Bun, Deno, edge runtimes.
+
+## Застарілі аліаси
+
+| Застарілий експорт         | Заміна          |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/uk/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-25
 title: Новий Intlayer v9 - Що нового?
 description: Дізнайтеся, що нового в Intlayer v9. Представляємо сумісні пакети швидкої заміни (drop-in) для популярних бібліотек i18n та підтримку Collections, Variants та Dynamic Records.
 keywords:
@@ -252,6 +252,28 @@ export default config;
 
 ---
 
+## React Native: імпорт з одного пакета
+
+У програмі React Native або Expo вам більше не потрібно жонглювати `react-intlayer` та `react-native-intlayer`. Пакет `react-native-intlayer` тепер **реекспортує весь API `react-intlayer`** (хуки, утиліти та підшляхи `/format`, `/html` і `/markdown`), а його `IntlayerProvider` автоматично застосовує поліфіли React Native.
+
+Імпортуйте все з єдиного пакета `react-native-intlayer`:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Імпорт з `react-intlayer` продовжує працювати, але `react-native-intlayer` тепер є рекомендованою єдиною точкою входу для React Native — його провайдер містить поліфіли, яких не має веб-орієнтований провайдер `react-intlayer`.
+
+---
+
 ## Примітки щодо міграції з v8
 
 Якщо ви оновлюєтеся з v8, зверніть увагу, що v9 не містить критичних змін (breaking changes). Проте ось ключові зміни:

package/docs/ur/custom_domains.md

@@ -172,10 +172,16 @@ Vite پلگ ان `intlayerProxy` ڈیولپمنٹ کے دوران اسی منط
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/ur/intlayer_with_storybook.md

@@ -152,7 +152,13 @@ const config: StorybookConfig = {
     } as const;
 
     const viteConfig = defineConfig(() => ({
-      plugins: [intlayer()],
+      plugins: [
+        intlayer({
+          proxy: {
+            ignore: (req) => req.url?.startsWith("/api"),
+          },
+        }),
+      ],
     }));
 
     return mergeConfig(baseConfig, viteConfig(env));

package/docs/ur/intlayer_with_vite+lit.md

@@ -167,7 +167,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -436,7 +442,7 @@ export class MyElement extends LitElement {
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [intlayer(), intlayerProxy()],

package/docs/ur/intlayer_with_vite+vanilla.md

@@ -167,7 +167,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -428,12 +434,15 @@ document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // اسے پہلے رکھنا چاہیے
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -565,6 +574,8 @@ bunx intlayer extract
  </Tab>
  <Tab value='Babel کمپائلر'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `intlayerCompiler` پلگ ان شامل کرنے کے لیے اپنی `vite.config.ts` اپ ڈیٹ کریں:
 
 ```ts fileName="vite.config.ts"
@@ -574,7 +585,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // کمپائلر پلگ ان شامل کرتا ہے
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/compiler.md

@@ -81,12 +81,15 @@ Cập nhật file `vite.config.ts` của bạn để bao gồm plugin `intlayerC
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/vi/custom_domains.md

@@ -172,10 +172,16 @@ Plugin Vite `intlayerProxy` áp dụng logic tương tự trong quá trình phá
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/vi/custom_url_rewrites.md

@@ -342,10 +342,16 @@ export function middleware(request: NextRequest) {
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/vi/intlayer_with_analog.md

@@ -207,7 +207,11 @@ import analog from "@analogjs/platform";
 export default defineConfig(() => ({
   plugins: [
     analog(),
-    intlayer(), // Thêm plugin Intlayer
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 }));
 ```

package/docs/vi/intlayer_with_astro.md

@@ -518,6 +518,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -527,7 +529,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_lit.md

@@ -604,6 +604,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -613,7 +615,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_preact.md

@@ -559,6 +559,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -568,7 +570,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_react.md

@@ -555,6 +555,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -564,7 +566,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_solid.md

@@ -555,6 +555,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -564,7 +566,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_svelte.md

@@ -559,6 +559,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -568,7 +570,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_vanilla.md

@@ -533,6 +533,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -542,7 +544,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_astro_vue.md

@@ -569,6 +569,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Cập nhật `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -578,7 +580,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Thêm plugin trình biên dịch
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/vi/intlayer_with_lynx+react.md

@@ -232,6 +232,8 @@ if (import.meta.webpackHot) {
 Tạo các file **khai báo nội dung** ở bất kỳ đâu trong dự án của bạn (thường là trong `src/`), sử dụng bất kỳ định dạng phần mở rộng nào mà Intlayer hỗ trợ:
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -239,7 +241,10 @@ Tạo các file **khai báo nội dung** ở bất kỳ đâu trong dự án c
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - v.v.
 
 Ví dụ:

package/docs/vi/intlayer_with_nextjs_15.md

@@ -1016,6 +1016,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/vi/intlayer_with_nextjs_16.md

@@ -997,6 +997,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/vi/intlayer_with_nextjs_compiler.md

@@ -559,6 +559,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Trình biên dịch Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```