@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

package/docs/vi/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: "Tài liệu Gói @intlayer/babel"
+description: Các plugin Babel cho Intlayer để xử lý trích xuất nội dung, tối ưu hóa nhập khẩu (import), loại bỏ các trường không sử dụng và mã hóa tên trường trong quá trình xây dựng (build).
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - đa ngôn ngữ
+  - i18n
+  - trình biên dịch
+  - tối ưu hóa
+  - loại bỏ
+  - thu nhỏ
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Hợp nhất tài liệu cho tất cả các xuất khẩu (exports)"
+author: aymericzip
+---
+
+# Gói @intlayer/babel
+
+Gói `@intlayer/babel` cung cấp một tập hợp các plugin Babel chuyên dụng cho Intlayer. Các plugin này bao gồm toàn bộ chu kỳ xây dựng: trích xuất các khai báo nội dung, viết lại các lệnh gọi `useIntlayer` / `getIntlayer` thành các lệnh nhập từ điển được tối ưu hóa, cắt bỏ các trường không sử dụng và nén tên trường.
+
+## Cài đặt
+
+```bash
+npm install @intlayer/babel
+```
+
+## Xuất khẩu (Exports)
+
+Nhập khẩu (Import):
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### Plugins
+
+| Hàm / Lớp                      | Mô tả                                                                                                                                                                                              |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`   | Plugin Babel trích xuất nội dung có thể dịch từ các tệp nguồn và tự động chèn các hook `useIntlayer` / `getIntlayer`. Được thiết kế để sử dụng với Next.js và các công cụ xây dựng dựa trên Babel. |
+| `intlayerOptimizeBabelPlugin`  | Plugin Babel chuyển đổi các lệnh gọi `useIntlayer` và `getIntlayer` và viết lại các lệnh nhập của chúng thành các lệnh nhập từ điển JSON được tối ưu hóa (tĩnh, động hoặc qua fetch).              |
+| `intlayerPurgeBabelPlugin`     | Plugin Babel phân tích các tệp nguồn và viết lại các tệp JSON từ điển đã biên dịch để loại bỏ các trường không sử dụng (`build.purge`) hoặc đổi tên chúng thành các bí danh ngắn (`build.minify`). |
+| `intlayerMinifyBabelPlugin`    | Plugin Babel viết lại các tệp nguồn để sử dụng các bí danh trường ngắn được chỉ định trong giai đoạn thu nhỏ (ví dụ: `content.title` ← `content.a`). Dựa vào `intlayerPurgeBabelPlugin`.           |
+| `makeFieldRenameBabelPlugin`   | Hàm tạo (factory) tạo ra một plugin Babel để đổi tên các truy cập trường nội dung từ điển trong các tệp nguồn theo `dictionaryKeyToFieldRenameMap` được điền trong `PruneContext`.                 |
+| `makeUsageAnalyzerBabelPlugin` | Hàm tạo tạo ra một plugin Babel để phân tích việc sử dụng `useIntlayer` / `getIntlayer` trong mã nguồn và tổng hợp dữ liệu sử dụng trường trong `PruneContext` chung.                              |
+| `getSharedPruneContext`        | Hàm trợ giúp trả về đối tượng `PruneContext` chung cho thư mục gốc đã chỉ định hoặc `null` nếu nó chưa được khởi tạo.                                                                              |
+
+---
+
+### Tiện ích cấu hình plugin
+
+| Hàm                        | Mô tả                                                                                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | Tải cấu hình Intlayer và trả về `ExtractPluginOptions` sẵn sàng sử dụng với `intlayerExtractBabelPlugin`.                                       |
+| `getOptimizePluginOptions` | Tải cấu hình Intlayer và các từ điển đã biên dịch, đồng thời trả về `OptimizePluginOptions` sẵn sàng sử dụng với `intlayerOptimizeBabelPlugin`. |
+| `getPurgePluginOptions`    | Tải cấu hình Intlayer và trả về `PurgePluginOptions` sẵn sàng sử dụng với `intlayerPurgeBabelPlugin`.                                           |
+| `getMinifyPluginOptions`   | Tải cấu hình Intlayer và trả về `MinifyPluginOptions` sẵn sàng sử dụng với `intlayerMinifyBabelPlugin`.                                         |
+
+---
+
+### Kiểu dữ liệu
+
+| Kiểu dữ liệu            | Mô tả                                                                                                                         |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `CompilerMode`          | Chế độ trình biên dịch: `'dev'` để phát triển với hỗ trợ HMR hoặc `'build'` cho các bản dựng production.                      |
+| `ExtractPluginOptions`  | Tùy chọn cho `intlayerExtractBabelPlugin`: danh sách tệp, cấu hình, callback `onExtract`, v.v.                                |
+| `ExtractResult`         | Kết quả trích xuất: khóa từ điển, đường dẫn tệp, nội dung và ngôn ngữ.                                                        |
+| `OptimizePluginOptions` | Tùy chọn cho `intlayerOptimizeBabelPlugin`: đường dẫn từ điển, chế độ nhập, bản đồ chế độ cho mỗi từ điển, v.v.               |
+| `PurgePluginOptions`    | Tùy chọn cho `intlayerPurgeBabelPlugin`: thư mục gốc, cờ purge/minify/optimize, danh sách tệp component.                      |
+| `MinifyPluginOptions`   | Tùy chọn cho `intlayerMinifyBabelPlugin`: thư mục gốc, cờ thu nhỏ/tối ưu hóa/editorEnabled.                                   |
+| `PruneContext`          | Trạng thái chia sẻ giữa các phân tích và các plugin cắt bỏ: bản đồ sử dụng trường, bản đồ đổi tên, v.v.                       |
+| `DictionaryFieldUsage`  | Kết quả sử dụng trường cho một từ điển duy nhất: `Set<string>` hoặc `'all'` khi phân tích tĩnh không đưa ra kết quả kết luận. |
+| `NestedRenameEntry`     | Một nút trong cây đổi tên: `shortName` và bản đồ các con.                                                                     |
+| `NestedRenameMap`       | Một cấp độ trong cây đổi tên: `Map<string, NestedRenameEntry>`.                                                               |
+| `CompatCallerConfig`    | Cấu hình cho bộ phân tích sử dụng tương thích cho các gói `compat-adapter` (tên người gọi và các tùy chọn xử lý).             |
+| `ScriptBlock`           | Khối script được trích xuất từ tệp SFC (Vue hoặc Svelte): nội dung, độ lệch bắt đầu và kết thúc.                              |
+
+---
+
+### Các hàm tiện ích
+
+| Hàm                               | Mô tả                                                                                                                                                         |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | Chuyển đổi một số nguyên (bắt đầu từ số không) thành mã định danh chữ cái ngắn: `0` → `'a'`, `25` → `'z'`, `26` → `'aa'`, v.v.                                |
+| `buildNestedRenameMapFromContent` | Xây dựng đệ quy một `NestedRenameMap` từ giá trị nội dung của một từ điển đã biên dịch, tôn trọng các cấu trúc nút Intlayer (translation, enumeration, v.v.). |
+| `createPruneContext`              | Tạo một đối tượng `PruneContext` trống mới được khởi tạo với các giá trị mặc định.                                                                            |
+| `extractScriptBlocks`             | Trích xuất các khối `<script>` từ các tệp SFC (Vue / Svelte) để phân tích Babel tiếp theo.                                                                    |
+| `BABEL_PARSER_OPTIONS`            | Hằng số đại diện cho các tùy chọn phân tích cú pháp Babel bao gồm các framework được hỗ trợ (React/Vue/Svelte/Angular/...).                                   |
+| `INTLAYER_CALLER_NAMES`           | Danh sách hằng số gồm các tên người gọi Intlayer ban đầu: `['useIntlayer', 'getIntlayer']`.                                                                   |
+
+---
+
+## Ví dụ sử dụng
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **Lưu ý:** Plugin `intlayerPurgeBabelPlugin` phải được khai báo **trước** `intlayerMinifyBabelPlugin`, vì plugin sau đọc bản đồ đổi tên được xây dựng bởi plugin trước. Ngoài ra, cả hai đều phải đứng sau `intlayerOptimizeBabelPlugin` để nó có thể nhìn thấy các khóa từ điển trước khi các lệnh gọi `useIntlayer` được viết lại.

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

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Tài liệu Plugin Vite intlayerCompiler | vite-intlayer
+description: Plugin Vite giúp trích xuất các khai báo nội dung Intlayer trực tiếp (inline) từ các tệp component và ghi chúng vào các tệp JSON từ điển tại thời điểm build/transform.
+keywords:
+  - intlayerCompiler
+  - vite
+  - plugin
+  - trình biên dịch
+  - nội dung
+  - từ điển
+  - đa ngôn ngữ
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Đã tích hợp vào intlayer(); khởi tạo tài liệu"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler` là một plugin Vite quét các tệp nguồn component để tìm **các khai báo nội dung Intlayer trực tiếp (inline)** — nội dung được định nghĩa trực tiếp bên trong một component thay vì trong một tệp `.content.ts` riêng biệt — và ghi chúng vào các tệp JSON từ điển trong giai đoạn transform (chuyển đổi).
+
+> **Từ phiên bản Intlayer v9**, `intlayerCompiler` đượ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) khi cả hai cấu hình `compiler.enabled` là `true` và `compiler.output` được thiết lập trong cấu hình Intlayer của bạn. Bạn chỉ cần đăng ký riêng khi muốn kiểm soát hoàn toàn cấu hình dành riêng cho trình biên dịch.
+
+## Cách sử dụng
+
+### Như một phần của `intlayer()` (khuyên dùng, v9+)
+
+Bật trình biên dịch thông qua cấu hình Intlayer của bạn:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // nơi ghi các từ điển đã được trích xuất
+  },
+});
+```
+
+Sau đó sử dụng plugin tiêu chuẩn mà không cần đăng ký thêm:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Độc lập (khi cần thiết)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## Các tùy chọn
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| Tùy chọn         | Kiểu dữ liệu              | Mô tả                                                                                                  |
+| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `configOptions`  | `GetConfigurationOptions` | Các giá trị ghi đè cấu hình Intlayer được chuyển tiếp đến `getConfiguration()`.                        |
+| `compilerConfig` | `Partial<CompilerConfig>` | Các ghi đè cho phần cấu hình dành riêng cho trình biên dịch (ví dụ: `enabled`, `output`, `filesList`). |
+
+### Ví dụ
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## Cách thức hoạt động
+
+### Giai đoạn Transform (Chuyển đổi)
+
+Đối với mỗi tệp nguồn khớp với `compiler.filesList`, plugin trình biên dịch sẽ:
+
+1. Chuyển nội dung tệp qua hàm `extractContent` từ thư viện `@intlayer/babel`.
+2. Gọi hàm `onExtract` cho mỗi khai báo được tìm thấy, thao tác này sẽ ghi JSON từ điển kết quả vào đường dẫn `compiler.output`.
+3. Trả về mã nguồn đã chuyển đổi với các khai báo inline được thay thế bằng các lệnh gọi tiêu chuẩn `useIntlayer('key')` / `getIntlayer('key')`.
+
+Các loại tệp được hỗ trợ: `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`.
+
+### HMR (Hot Module Replacement - Thay thế mô-đun nóng)
+
+Khi một tệp component được lưu ở chế độ phát triển (development mode), trình biên dịch sẽ:
+
+1. Phát hiện tệp thay đổi thông qua hook `handleHotUpdate` của Vite.
+2. Trích xuất lại nội dung từ tệp đã cập nhật.
+3. Ghi tệp JSON từ điển đã cập nhật.
+4. Kích hoạt tải lại toàn bộ trang (`server.ws.send({ type: 'full-reload' })`).
+
+Một khoảng thời gian debounce (chống rung) 500 ms ngăn việc ghi từ điển (cũng kích hoạt sự kiện thay đổi tệp) tạo ra một vòng lặp trích xuất vô hạn.
+
+### Khử trùng lặp (Deduplication)
+
+`intlayerCompiler` sử dụng cùng một cơ chế khử trùng lặp `createPrimaryInstanceGuard` giống như các plugin đi kèm khác. Khi cả `intlayer()` (gộp cả trình biên dịch) và lệnh gọi `intlayerCompiler()` thủ công đều xuất hiện, chỉ có phiên bản đã đăng ký đầu tiên chạy — không có từ điển nào bị ghi đè hai lần.

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

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Tài liệu Plugin Vite intlayerMinify | vite-intlayer
+description: Plugin Vite giúp nén (minify) các tệp JSON từ điển Intlayer đã biên dịch và tùy chọn mã hóa các tên trường nội dung để giảm kích thước gói bundle.
+keywords:
+  - intlayerMinify
+  - vite
+  - plugin
+  - nén
+  - kích thước bundle
+  - từ điển
+  - đa ngôn ngữ
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Khởi tạo tài liệu"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify` là một plugin Vite nén các tệp JSON từ điển đã biên dịch trong quá trình build production. Nó loại bỏ tất cả khoảng trắng không cần thiết và khi kết hợp với `intlayerPrune`, có thể tùy chọn đổi tên các trường nội dung thành các bí danh ngắn (`a`, `b`, `c`, …) để giảm thiểu hơn nữa kích thước gói bundle.
+
+> Plugin này đã được tích hợp và cấu hình tự động khi bạn sử dụng [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/vite-intlayer/intlayer.md). Bạn chỉ cần tự đăng ký thủ công nếu đang tự thiết lập cấu trúc plugin của riêng mình.
+
+## Cách sử dụng
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## Điều kiện kích hoạt
+
+`intlayerMinify` chỉ hoạt động **khi và chỉ khi** cả ba điều kiện sau đều đúng:
+
+1. Lệnh Vite chạy là `build` (không phải `serve` / dev).
+2. Tùy chọn `build.optimize` là `true` (hoặc `undefined`, mặc định sẽ là `true` đối với tiến trình build).
+3. Tùy chọn `build.minify` được đặt là `true` trong cấu hình Intlayer của bạn.
+
+Nó tự động bị **vô hiệu hóa** khi `editor.enabled` là `true` vì editor cần nội dung từ điển đầy đủ và thân thiện với người đọc.
+
+## Những gì được nén
+
+Plugin nhắm vào hai vị trí từ điển (được phân giải từ `intlayer.system`):
+
+- `dictionariesDir` — các từ điển tĩnh cho tất cả các locale (ví dụ: `.intlayer/dictionaries/*.json`)
+- `dynamicDictionariesDir` — các từ điển động cho mỗi locale
+
+> Các từ điển sử dụng chế độ fetch (`fetchDictionariesDir`) sẽ **không bao giờ** bị nén vì chúng được cung cấp từ một API từ xa tại thời điểm chạy bằng cách sử dụng các tên trường gốc. Việc đổi tên các trường sẽ tạo ra sự không khớp giữa phản hồi của máy chủ và các thuộc tính được truy cập phía client.
+
+## Mã hóa tên trường (Thu nhỏ thuộc tính)
+
+Khi `intlayerPrune` đã phân tích mã nguồn và cập nhật dữ liệu cho `pruneContext.dictionaryKeyToFieldRenameMap`, `intlayerMinify` cũng đổi tên các trường nội dung thành các bí danh ngắn. Ví dụ:
+
+```json
+// trước khi đổi
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// sau khi đổi (đã được mã hóa)
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+Các thuộc tính truy cập trong tệp nguồn tương ứng được đổi tên bằng bước xử lý Babel bên trong `intlayerOptimize`, do đó hành vi runtime không bị thay đổi.
+
+Các trường nội bộ của Intlayer (`nodeType`, `translation`, v.v.) không bao giờ bị đổi tên.
+
+## Các từ điển trường hợp đặc biệt (Edge-cases)
+
+Các từ điển được gắn cờ trong `pruneContext.dictionariesWithEdgeCases` (phát hiện bất thường về cấu trúc trong giai đoạn prune) sẽ được bỏ qua hoàn toàn — không nén hay mã hóa — để tránh gửi dữ liệu bị hỏng.
+
+## Nhóm đủ điều kiện (Bộ sưu tập / Biến thể / Bản ghi meta)
+
+Đối với các từ điển có mảng `qualifierTypes` (bộ sưu tập, biến thể và bản ghi meta), plugin giữ nguyên mảng `qualifierTypes` và bản đồ phụ `meta` một cách nguyên văn. Chỉ có các mục nhập `content` bị mã hóa tên trường. Các khóa phức hợp (được sử dụng để đối sánh bộ chọn tại thời điểm chạy) không bao giờ bị can thiệp.

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/plugins/sync-json.md

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * Will load, and write the output and translations back to the JSON files in the locales directory
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",