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

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

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Tài liệu Plugin Vite intlayerProxy | vite-intlayer
+description: Middleware định tuyến ngôn ngữ cho các máy chủ dev/preview của Vite và SSR production. Xử lý phát hiện locale, chuyển hướng URL và viết lại (rewrite) nội bộ.
+keywords:
+  - intlayerProxy
+  - vite
+  - plugin
+  - middleware
+  - locale
+  - định tuyến
+  - đa ngôn ngữ
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Gộp configOptions thành một đối tượng tùy chọn duy nhất; proxy được tích hợp trong intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` là một plugin Vite đăng ký middleware định tuyến locale cho **mọi môi trường**: máy chủ phát triển (dev), máy chủ xem trước (preview) và SSR sản xuất (Nitro / TanStack Start).
+
+> **Từ phiên bản Intlayer v9**, `intlayerProxy` được tự động bao gồm bên trong plugin chính [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/vite-intlayer/intlayer.md) và được bật mặc định thông qua cấu hình `routing.enableProxy: true`. Bạn chỉ cần đăng ký riêng nếu cần kiểm soát ở mức thấp hơn hoặc đang sử dụng bên ngoài thiết lập `intlayer()` tiêu chuẩn.
+
+## Cách sử dụng
+
+### Như một phần của `intlayer()` (khuyên dùng, v9+)
+
+Truyền các tùy chọn `proxy` cho plugin chính thay vì đăng ký `intlayerProxy` riêng biệt:
+
+```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"),
+      },
+    }),
+  ],
+});
+```
+
+### Độc lập (khi cần thiết)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Các tùy chọn
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+Tất cả các tùy chọn đều không bắt buộc và được truyền dưới dạng một đối tượng duy nhất:
+
+| Tùy chọn        | Kiểu dữ liệu                        | Mô tả                                                                                                                                                  |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Hàm điều kiện giúp loại trừ các yêu cầu khỏi định tuyến ngôn ngữ. Trả về `true` để bỏ qua một yêu cầu (ví dụ: các đường dẫn API, kiểm tra sức khỏe).   |
+| `configOptions` | `GetConfigurationOptions`           | Các ghi đè cấu hình Intlayer được chuyển tiếp đến `getConfiguration()`. Sử dụng khi bạn cần proxy đọc một tệp cấu hình cụ thể hoặc ghi đè các giá trị. |
+
+### Ví dụ
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` tạo một middleware độc lập, không phụ thuộc vào framework dành cho Node.js dạng `(req, res, next)` chứa toàn bộ logic định tuyến ngôn ngữ. Nó hữu ích trong các môi trường không có sẵn API của plugin Vite (ví dụ: một máy chủ Node.js đơn giản hoặc một mô-đun Nitro tùy chỉnh).
+
+```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 Sản xuất (TanStack Start / Nitro thông qua 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"),
+  })
+);
+```
+
+## Hành vi định tuyến
+
+Middleware phản chiếu logic định tuyến từ middleware `next-intlayer` và hỗ trợ tất cả các chế độ định tuyến của Intlayer.
+
+### Các chế độ định tuyến
+
+| Chế độ          | URL hiển thị trên trình duyệt | Hành vi                                                                                                               |
+| --------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/vi/about`                   | Mặc định. Tiền tố locale trong URL. Ngôn ngữ mặc định chuyển hướng đến URL không có tiền tố trừ khi bật `prefix-all`. |
+| `prefix-all`    | `/en/about`, `/vi/about`      | Tất cả các ngôn ngữ — bao gồm cả mặc định — đều luôn có tiền tố.                                                      |
+| `no-prefix`     | `/about`                      | Không có ngôn ngữ trong URL. Ngôn ngữ chỉ được lưu trữ trong cookie; việc viết lại URL diễn ra nội bộ.                |
+| `search-params` | `/about?locale=vi`            | Ngôn ngữ được truyền dưới dạng tham số truy vấn. Chuyển hướng để thêm/cập nhật tham số `locale` khi thiếu hoặc cũ.    |
+
+### Mức độ ưu tiên phát hiện
+
+1. Tiền tố đường dẫn URL (ví dụ: `/vi/about` → `vi`).
+2. Giá trị cookie / localStorage (`intlayer-locale`).
+3. Tiêu đề `Accept-Language`.
+4. `defaultLocale` từ cấu hình.
+
+### Bỏ qua tự động
+
+Middleware luôn cho phép các yêu cầu sau đi thẳng mà không cần xử lý locale:
+
+- Các yêu cầu khớp với hàm điều kiện `ignore`.
+- `/node_modules/**`
+- `/@**` – các thành phần nội bộ của Vite (`@vite/`, `@fs/`, `@id/`, v.v.).
+- `/_**` – các thành phần nội bộ của máy chủ (`__vite_ping`, `__manifest`, v.v.).
+- Các yêu cầu có đường dẫn kết thúc bằng phần mở rộng tệp (tài nguyên tĩnh). Nếu tiền tố locale xuất hiện trên đường dẫn tài nguyên tĩnh (ví dụ: `/vi/logo.png`), nó sẽ bị loại bỏ để tệp có thể được phân phát chính xác.
+
+### Định tuyến tên miền
+
+Khi `routing.domains` được định cấu hình trong cấu hình Intlayer của bạn, middleware sẽ xử lý định tuyến locale chéo miền:
+
+- Một yêu cầu cho `/zh/about` trên `intlayer.org` sẽ được chuyển hướng đến `https://intlayer.zh/about` khi `domains.zh = "intlayer.zh"`.
+- Một yêu cầu đến `intlayer.zh/about` được viết lại nội bộ thành `/zh/about` để tham số tuyến đường `[locale]` được cập nhật dữ liệu.
+
+### Bảo vệ vòng lặp chuyển hướng
+
+Middleware theo dõi số lần chuyển hướng cho mỗi cặp `originalUrl → newUrl` trong một khoảng thời gian trượt (sliding window) dài 2 giây. Hơn 10 lần chuyển hướng trong khoảng thời gian đó sẽ trả về phản hồi `500` kèm theo mô tả lỗi chi tiết thay vì lặp lại mãi mãi.
+
+## Nitro / SSR sản xuất (tự động đưa vào, v9+)
+
+Khi `intlayerProxy` được sử dụng dưới dạng plugin Vite, nó mang thuộc tính `.nitro`. Plugin xây dựng `nitro/vite` đọc thuộc tính này và đẩy nó vào `nitroConfig.modules`, do đó `intlayerNitroHandler` được đăng ký làm middleware máy chủ Nitro tự động — không cần cấu hình thủ công cho SSR sản xuất.
+
+Trình xử lý Nitro sử dụng mô hình sự kiện Web Fetch API của h3 v2 (không phải `fromNodeMiddleware`) nên nó tương thích với tất cả các cấu hình Nitro: Node, Bun, Deno, edge runtimes.
+
+## Các bí danh lỗi thời
+
+| Xuất khẩu lỗi thời         | Thay thế        |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/vi/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-25
 title: Intlayer v9 Mới - Có gì mới?
 description: Khám phá các tính năng mới trong Intlayer v9. Giới thiệu các package tương thích drop-in cho các thư viện i18n phổ biến và hỗ trợ Collections, Variants, và Dynamic Records.
 keywords:
@@ -252,6 +252,28 @@ Các plugin độc lập `intlayerCompiler()` và `intlayerProxy()` vẫn đư
 
 ---
 
+## React Native: import từ một package duy nhất
+
+Trong ứng dụng React Native hoặc Expo, bạn không còn cần phải xoay sở giữa `react-intlayer` và `react-native-intlayer` nữa. Package `react-native-intlayer` hiện **xuất lại toàn bộ API của `react-intlayer`** (các hook, tiện ích và các đường dẫn phụ `/format`, `/html`, và `/markdown`), và `IntlayerProvider` của nó tự động áp dụng các polyfill của React Native.
+
+Import mọi thứ từ package `react-native-intlayer` duy nhất:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Việc import từ `react-intlayer` vẫn tiếp tục hoạt động, nhưng `react-native-intlayer` hiện là điểm vào duy nhất được khuyên dùng cho React Native — provider của nó cung cấp các polyfill mà provider định hướng web `react-intlayer` không có.
+
+---
+
 ## Lưu ý khi migration từ v8
 
 Nếu bạn đang nâng cấp từ v8, lưu ý rằng v9 không bao gồm các breaking change. Tuy nhiên, dưới đây là các thay đổi chính:

package/docs/zh/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(), // 添加编译器插件
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/zh/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/zh/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/zh/intlayer_with_astro.md

@@ -539,6 +539,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -548,7 +550,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_lit.md

@@ -590,6 +590,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -599,7 +601,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_preact.md

@@ -545,6 +545,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -554,7 +556,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_react.md

@@ -541,6 +541,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -550,7 +552,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_solid.md

@@ -541,6 +541,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -550,7 +552,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_svelte.md

@@ -545,6 +545,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -554,7 +556,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_vanilla.md

@@ -519,6 +519,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -528,7 +530,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_vue.md

@@ -563,6 +563,8 @@ bun x 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.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -572,7 +574,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_nextjs_16.md

@@ -993,6 +993,8 @@ bun x 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.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/zh/intlayer_with_nextjs_compiler.md

@@ -583,6 +583,8 @@ bun x 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.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```