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

package/docs/ru/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/ru/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`        | `/ru/about`              | По умолчанию. Префикс языка в URL. Язык по умолчанию перенаправляет на URL без префикса, если не активен `prefix-all`.            |
+| `prefix-all`    | `/en/about`, `/ru/about` | Все языки (включая язык по умолчанию) всегда имеют префикс в URL.                                                                 |
+| `no-prefix`     | `/about`                 | Нет языка в URL. Язык сохраняется только в cookies; перезапись URL происходит на внутреннем уровне.                               |
+| `search-params` | `/about?locale=ru`       | Язык передается как query-параметр. Перенаправляет для добавления/обновления параметра `locale`, если он отсутствует или устарел. |
+
+### Приоритет определения
+
+1. Префикс пути URL (например, `/ru/about` → `ru`).
+2. Значение в cookie / localStorage (`intlayer-locale`).
+3. Заголовок `Accept-Language`.
+4. `defaultLocale` из конфигурации.
+
+### Автоматический обход (Bypass)
+
+Этот middleware всегда пропускает следующие запросы напрямую без обработки локали:
+
+- Запросы, соответствующие предикату `ignore`.
+- `/node_modules/**`
+- `/@**` — внутренние запросы Vite (`@vite/`, `@fs/`, `@id/` и т.д.).
+- `/_**` — внутренние запросы сервера (`__vite_ping`, `__manifest` и т.д.).
+- Запросы, путь которых заканчивается расширением файла (статические файлы). Если в пути статического файла присутствует языковой префикс (например, `/ru/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/ru/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/tr/compiler.md

@@ -81,12 +81,15 @@ npm install vite-intlayer
 
 ```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(), // Derleyici eklentisini ekler
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/tr/custom_domains.md

@@ -172,10 +172,16 @@ GET intlayer.zh/about
 
 ```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/tr/custom_url_rewrites.md

@@ -342,10 +342,16 @@ SolidJS, Vue ve Svelte için `intlayerProxy` Vite eklentisi geliştirme sırası
 
 ```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/tr/intlayer_with_analog.md

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

package/docs/tr/intlayer_with_astro_lit.md

@@ -596,6 +596,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -605,7 +607,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_astro_preact.md

@@ -551,6 +551,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -560,7 +562,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_astro_react.md

@@ -547,6 +547,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -556,7 +558,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_astro_solid.md

@@ -547,6 +547,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -556,7 +558,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_astro_svelte.md

@@ -551,6 +551,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -560,7 +562,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_astro_vanilla.md

@@ -525,6 +525,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -534,7 +536,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_astro_vue.md

@@ -569,6 +569,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts` dosyanızı `intlayerCompiler` eklentisini içerecek şekilde güncelleyin:
 
 ```ts fileName="vite.config.ts"
@@ -578,7 +580,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Derleyici eklentisini ekler
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/tr/intlayer_with_lynx+react.md

@@ -223,6 +223,8 @@ if (import.meta.webpackHot) {
 Projenizde herhangi bir yerde **içerik bildirim** dosyaları oluşturun (genellikle `src/` içinde), Intlayer'ın desteklediği uzantı formatlarından herhangi birini kullanarak:
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -230,7 +232,10 @@ Projenizde herhangi bir yerde **içerik bildirim** dosyaları oluşturun (genell
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - vb.
 
 Örnek:

package/docs/tr/intlayer_with_nextjs_16.md

@@ -995,6 +995,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> 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/tr/intlayer_with_nextjs_compiler.md

@@ -559,6 +559,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel derleyicisi'>
 
+> 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
 ```