intlayerProxy

intlayerProxy — это плагин Vite, который регистрирует промежуточное ПО (middleware) локализации роутинга для любой среды: dev-сервера, preview-сервера и продакшен SSR (Nitro / TanStack Start).

Начиная с Intlayer v9 intlayerProxy автоматически включается в основной плагин intlayer() и активирован по умолчанию с помощью настройки routing.enableProxy: true. Вам нужно регистрировать его отдельно только в том случае, если вам нужен низкоуровневый контроль или если вы используете его за пределами стандартной конфигурации intlayer().

Использование

В составе intlayer() (рекомендуется, v9+)

Передайте параметры proxy в основной плагин вместо отдельной регистрации intlayerProxy:

// vite.config.tsimport { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [    intlayer({      proxy: {        ignore: (req) => req.url?.startsWith("/api"),      },    }),  ],});

Отдельно (при необходимости)

// vite.config.tsimport { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

Параметры

import type { IntlayerProxyPluginOptions } from "vite-intlayer";

Все параметры являются необязательными и передаются в виде единого объекта:

Пример

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).

import { createIntlayerProxyHandler } from "vite-intlayer";const handler = createIntlayerProxyHandler({  ignore: (req) => req.url?.startsWith("/api"),  configOptions: { configFile: "./config/intlayer.config.ts" },});// Express / Connectapp.use(handler);

Продакшен SSR (TanStack Start / Nitro через h3)

// server/middleware/intlayerProxy.tsimport { fromNodeMiddleware } from "h3";import { createIntlayerProxyHandler } from "vite-intlayer";export default fromNodeMiddleware(  createIntlayerProxyHandler({    ignore: (req) => req.url?.startsWith("/api"),  }));

Поведение роутинга

Этот middleware дублирует логику роутинга из middleware next-intlayer и поддерживает все режимы роутинга Intlayer.

Режимы роутинга

Приоритет определения

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.

Устаревшие алиасы