intlayerProxy

intlayerProxy to wtyczka Vite, która rejestruje oprogramowanie pośredniczące (middleware) do routingu języków dla każdego środowiska: serwera deweloperskiego, serwera podglądu i produkcyjnego SSR (Nitro / TanStack Start).

Od Intlayer v9 intlayerProxy jest automatycznie dołączany do głównej wtyczki intlayer() i domyślnie włączony poprzez routing.enableProxy: true. Musisz go zarejestrować osobno tylko wtedy, gdy potrzebujesz kontroli na niższym poziomie lub używasz go poza standardową konfiguracją intlayer().

Użycie

Jako część intlayer() (zalecane, v9+)

Przekaż opcje proxy do głównej wtyczki zamiast rejestrować intlayerProxy osobno:

// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

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

Samodzielnie (w razie potrzeby)

// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer()],
});

Opcje

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

Wszystkie opcje są opcjonalne i przekazywane jako pojedynczy obiekt:

Przykład

intlayerProxy({
  ignore: (req) => req.url?.startsWith("/api"),
  configOptions: { configFile: "./config/intlayer.config.ts" },
});

createIntlayerProxyHandler

createIntlayerProxyHandler tworzy samodzielne, niezależne od frameworka oprogramowanie pośredniczące Node.js (req, res, next), które zawiera całą logikę routingu języków. Jest przydatne w środowiskach, w których API wtyczek Vite jest niedostępne (np. czysty serwer Node.js lub niestandardowy moduł Nitro).

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

Produkcyjny SSR (TanStack Start / Nitro przez h3)

// server/middleware/intlayerProxy.ts
import { fromNodeMiddleware } from "h3";
import { createIntlayerProxyHandler } from "vite-intlayer";

export default fromNodeMiddleware(
  createIntlayerProxyHandler({
    ignore: (req) => req.url?.startsWith("/api"),
  })
);

Zachowanie routingu

Oprogramowanie pośredniczące odzwierciedla logikę routingu z middleware next-intlayer i obsługuje wszystkie tryby routingu Intlayer.

Tryby routingu

Priorytet wykrywania

1. Prefiks ścieżki URL (np. /pl/about → pl).
2. Wartość pliku cookie / localStorage (intlayer-locale).
3. Nagłówek Accept-Language.
4. defaultLocale z konfiguracji.

Automatyczne pomijanie (bypass)

Oprogramowanie pośredniczące zawsze przepuszcza te żądania bezpośrednio, bez obsługi języka:

• Żądania pasujące do predykatu ignore.
• /node_modules/**
• /@** – wewnętrzne zasoby Vite (@vite/, @fs/, @id/ itp.).
• /_** – wewnętrzne zasoby serwera (__vite_ping, __manifest itp.).
• Żądania, których ścieżka kończy się rozszerzeniem pliku (zasoby statyczne). Jeśli w ścieżce zasobu statycznego obecny jest prefiks języka (np. /pl/logo.png), zostaje on usunięty, aby plik mógł być serwowany poprawnie.

Routing domenowy

Gdy w konfiguracji Intlayer skonfigurowano routing.domains, oprogramowanie pośredniczące obsługuje routing językowy między różnymi domenami:

• Żądanie dla /zh/about w domenie intlayer.org jest przekierowywane na https://intlayer.zh/about, gdy domains.zh = "intlayer.zh".
• Żądanie do intlayer.zh/about jest wewnętrznie przepisywane na /zh/about, aby parametr trasy [locale] został uzupełniony.

Ochrona przed pętlą przekierowań

Oprogramowanie pośredniczące śledzi liczbę przekierowań dla pary originalUrl → newUrl w ruchomym oknie 2 sekund. Więcej niż 10 przekierowań w tym oknie zwraca odpowiedź 500 z opisowym błędem zamiast zapętlania się w nieskończoność.

Nitro / produkcyjny SSR (automatyczna iniekcja, v9+)

Gdy intlayerProxy jest używany jako wtyczka Vite, niesie ze sobą właściwość .nitro. Wtyczka budująca nitro/vite odczytuje tę właściwość i wstrzykuje ją do nitroConfig.modules, dzięki czemu intlayerNitroHandler rejestruje się jako serwerowe oprogramowanie pośredniczące Nitro automatycznie — dla produkcyjnego SSR nie jest wymagana żadna ręczna konfiguracja.

Handler Nitro korzysta z modelu zdarzeń Web Fetch API h3 v2 (nie fromNodeMiddleware), więc jest kompatybilny ze wszystkimi szablonami (presets) Nitro: Node, Bun, Deno, środowiskami edge.

Zdeprecjonowane aliasy