@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/vi/packages/solid-intlayer/usePathname.md

@@ -0,0 +1,119 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Tài liệu Hook usePathname | solid-intlayer
+description: Tìm hiểu cách sử dụng hook usePathname từ gói solid-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Quốc tế hóa
+  - Tài liệu
+  - Solid
+  - Solid.js
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - solid-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Tích hợp Solid: Tài liệu Hook `usePathname`
+
+Hook `usePathname` trả về pathname của trình duyệt hiện tại với phần locale đã bị loại bỏ, dưới dạng một `Accessor<string>` của Solid. Nó hữu ích cho việc xây dựng điều hướng nhận biết locale — ví dụ, xác định mục điều hướng nào đang hoạt động — mà không cần phải loại bỏ tiền tố locale theo cách thủ công.
+
+## Import `usePathname` trong Solid
+
+```typescript
+import { usePathname } from "solid-intlayer";
+```
+
+## Tổng quan
+
+`usePathname` tạo ra một reactive signal được khởi tạo từ `window.location.pathname`, loại bỏ tiền tố locale thông qua `getPathWithoutLocale`, và cập nhật signal mỗi khi trình duyệt kích hoạt sự kiện `popstate` (điều hướng quay lại/tiến lên). Event listener sẽ tự động được dọn dẹp thông qua `onCleanup`.
+
+## Sử dụng
+
+```tsx fileName="src/components/NavItem.tsx"
+import type { Component } from "solid-js";
+import { usePathname } from "solid-intlayer";
+
+type NavItemProps = {
+  href: string;
+  label: string;
+};
+
+const NavItem: Component<NavItemProps> = ({ href, label }) => {
+  const pathname = usePathname();
+
+  return (
+    <a href={href} aria-current={pathname() === href ? "page" : undefined}>
+      {label}
+    </a>
+  );
+};
+
+export default NavItem;
+```
+
+## Giá trị trả về
+
+| Kiểu dữ liệu       | Mô tả                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `Accessor<string>` | Accessor của Solid (reactive getter) trả về pathname hiện tại không bao gồm tiền tố locale. |
+
+## Hành vi
+
+- **Loại bỏ locale**: Xóa bỏ phần locale ở đầu pathname (ví dụ: `/vi/dashboard` → `/dashboard`).
+- **Reactive (Phản ứng)**: Tự động cập nhật dựa trên các sự kiện `popstate` (điều hướng quay lại / tiến lên của trình duyệt).
+- **An toàn cho SSR**: Trả về `""` khi `window` không có sẵn.
+- **Dọn dẹp**: `popstate` listener được loại bỏ tự động thông qua hàm `onCleanup` của Solid.
+
+## Ví dụ
+
+```tsx fileName="src/components/Sidebar.tsx"
+import type { Component } from "solid-js";
+import { For } from "solid-js";
+import { usePathname } from "solid-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Bảng điều khiển" },
+  { href: "/settings", label: "Cài đặt" },
+];
+
+const Sidebar: Component = () => {
+  const pathname = usePathname();
+
+  return (
+    <nav>
+      <For each={links}>
+        {({ href, label }) => (
+          <a
+            href={href}
+            style={{ "font-weight": pathname() === href ? "bold" : "normal" }}
+          >
+            {label}
+          </a>
+        )}
+      </For>
+    </nav>
+  );
+};
+
+export default Sidebar;
+```
+
+## Các tài liệu liên quan
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/solid-intlayer/useLocale.md) — locale hiện tại + bộ chuyển đổi locale
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md) — tiện ích nền tảng được sử dụng bởi hook này

package/docs/vi/packages/svelte-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - svelte-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Hợp nhất tài liệu cho tất cả các exports"
@@ -64,15 +67,16 @@ Nhập:
 import "svelte-intlayer";
 ```
 
-| Hàm                    | Mô tả                                                                                                                  | Tài liệu liên quan                                                                                                       |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `useIntlayer`          | Dựa trên `useDictionary`, nhưng chèn một phiên bản tối ưu của dictionary từ khai báo được sinh ra.                     | -                                                                                                                        |
-| `useDictionary`        | Xử lý các đối tượng có dạng dictionary (key, content). Nó xử lý các bản dịch `t()`, các enumeration, v.v.              | -                                                                                                                        |
-| `useDictionaryAsync`   | Tương tự `useDictionary`, nhưng xử lý các dictionary bất đồng bộ.                                                      | -                                                                                                                        |
-| `useDictionaryDynamic` | Tương tự `useDictionary`, nhưng xử lý các dictionary động.                                                             | -                                                                                                                        |
-| `useLocale`            | Trả về locale hiện tại và một hàm để thiết lập nó.                                                                     | -                                                                                                                        |
-| `useRewriteURL`        | Hàm phía client để quản lý việc rewrite URL. Tự động cập nhật URL nếu tồn tại một quy tắc rewrite đã được bản địa hóa. | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/svelte-intlayer/useRewriteURL.md) |
-| `useIntl`              | Trả về đối tượng Intl cho locale hiện tại.                                                                             | -                                                                                                                        |
+| Hàm                    | Mô tả                                                                                                                      | Tài liệu liên quan                                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `useIntlayer`          | Dựa trên `useDictionary`, nhưng chèn một phiên bản tối ưu của dictionary từ khai báo được sinh ra.                         | -                                                                                                                        |
+| `useDictionary`        | Xử lý các đối tượng có dạng dictionary (key, content). Nó xử lý các bản dịch `t()`, các enumeration, v.v.                  | -                                                                                                                        |
+| `useDictionaryAsync`   | Tương tự `useDictionary`, nhưng xử lý các dictionary bất đồng bộ.                                                          | -                                                                                                                        |
+| `useDictionaryDynamic` | Tương tự `useDictionary`, nhưng xử lý các dictionary động.                                                                 | -                                                                                                                        |
+| `useLocale`            | Trả về locale hiện tại và một hàm để thiết lập nó.                                                                         | -                                                                                                                        |
+| `usePathname`          | Trả về pathname hiện tại dưới dạng một `Readable<string>` store với phần locale đã bị loại bỏ. Có phản ứng với `popstate`. | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/svelte-intlayer/usePathname.md)     |
+| `useRewriteURL`        | Hàm phía client để quản lý việc rewrite URL. Tự động cập nhật URL nếu tồn tại một quy tắc rewrite đã được bản địa hóa.     | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/svelte-intlayer/useRewriteURL.md) |
+| `useIntl`              | Trả về đối tượng Intl cho locale hiện tại.                                                                                 | -                                                                                                                        |
 
 ### Markdown
 

package/docs/vi/packages/svelte-intlayer/usePathname.md

@@ -0,0 +1,103 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Tài liệu hàm usePathname | svelte-intlayer
+description: Tìm hiểu cách sử dụng hàm usePathname từ gói svelte-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Quốc tế hóa
+  - Tài liệu
+  - Svelte
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - svelte-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Tích hợp Svelte: Tài liệu `usePathname`
+
+Hàm `usePathname` trả về pathname của trình duyệt hiện tại với phần locale đã bị loại bỏ, dưới dạng một Svelte `Readable<string>` store. Nó hữu ích cho việc xây dựng điều hướng nhận biết locale — ví dụ, xác định mục điều hướng nào đang hoạt động — mà không cần phải loại bỏ tiền tố locale theo cách thủ công.
+
+## Import `usePathname` trong Svelte
+
+```typescript
+import { usePathname } from "svelte-intlayer";
+```
+
+## Tổng quan
+
+`usePathname` tạo ra một Svelte readable store được khởi tạo từ `window.location.pathname`, loại bỏ tiền tố locale thông qua `getPathWithoutLocale`, và phát ra một giá trị mới mỗi khi trình duyệt kích hoạt sự kiện `popstate` (điều hướng quay lại/tiến lên). Đăng ký theo dõi (subscribe) bằng cú pháp `$` trong các component.
+
+## Sử dụng
+
+```svelte fileName="src/components/NavItem.svelte"
+<script lang="ts">
+  import { usePathname } from "svelte-intlayer";
+
+  export let href: string;
+  export let label: string;
+
+  const pathname = usePathname();
+</script>
+
+<a {href} aria-current={$pathname === href ? "page" : undefined}>
+  {label}
+</a>
+```
+
+## Giá trị trả về
+
+| Kiểu dữ liệu       | Mô tả                                                                      |
+| ------------------ | -------------------------------------------------------------------------- |
+| `Readable<string>` | Svelte readable store chứa pathname hiện tại không bao gồm tiền tố locale. |
+
+## Hành vi
+
+- **Loại bỏ locale**: Xóa bỏ phần locale ở đầu pathname (ví dụ: `/vi/dashboard` → `/dashboard`).
+- **Phản ứng (Reactive)**: Phát ra giá trị mới trên mỗi sự kiện `popstate` (điều hướng quay lại / tiến lên của trình duyệt).
+- **An toàn cho SSR**: Trả về `""` khi `window` không có sẵn.
+- **Dọn dẹp**: `popstate` listener được loại bỏ tự động khi subscriber cuối cùng hủy đăng ký.
+
+## Ví dụ
+
+```svelte fileName="src/components/Sidebar.svelte"
+<script lang="ts">
+  import { usePathname } from "svelte-intlayer";
+
+  const links = [
+    { href: "/dashboard", label: "Bảng điều khiển" },
+    { href: "/settings", label: "Cài đặt" },
+  ];
+
+  const pathname = usePathname();
+</script>
+
+<nav>
+  {#each links as link}
+    <a
+      href={link.href}
+      style:font-weight={$pathname === link.href ? "bold" : "normal"}
+    >
+      {link.label}
+    </a>
+  {/each}
+</nav>
+```
+
+## Các tài liệu liên quan
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/svelte-intlayer/useLocale.md) — locale hiện tại + bộ chuyển đổi locale
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md) — tiện ích nền tảng được sử dụng bởi hook này

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` |