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

package/docs/uk/releases/v7.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 Ласкаво просимо до Intlayer v7! Це велике оновлення вводить суттєві покращення продуктивності, type safety і developer experience. Нижче наведено основні зміни, нотатки щодо міграції та практичні приклади.
 
+## Зміст
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## Основні моменти
 
 - Підтримка Next.js 16

package/docs/uk/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-06-23
 title: Новий Intlayer v9 - Що нового?
 description: Дізнайтеся, що нового в Intlayer v9. Представляємо сумісні пакети швидкої заміни (drop-in) для популярних бібліотек i18n та підтримку Collections, Variants та Dynamic Records.
 keywords:
@@ -216,6 +216,42 @@ export default {
 
 ---
 
+## Vite Plugin: Bundled Compiler & Proxy
+
+Плагін Vite `intlayer()` тепер об'єднує **компілятор** та **проксі для маршрутизації локалей** безпосередньо, тому більшості проектів потрібен лише один плагін у `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: Активується автоматично, коли встановлено `compiler.enabled` та налаштована шлях `compiler.output`. Вам більше не потрібно реєструвати `intlayerCompiler()` окремо.
+- **Proxy**: Активується автоматично на основі нового параметра `routing.enableProxy` (`true` за замовчуванням). Він підключає middleware виявлення локалей / перенаправлення / переписування в режимі розробки, попереднього перегляду та production SSR. Вам більше не потрібно реєструвати `intlayerProxy()` окремо.
+
+### Опція `routing.enableProxy`
+
+Нова опція `routing.enableProxy` контролює, чи підключений проксі маршрутизації локалі. За замовчуванням встановлено значення `true`. Вимкніть її, якщо ви хочете самостійно обробляти маршрутизацію локалі:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // За замовчуванням: true
+  },
+};
+
+export default config;
+```
+
+Автономні плагіни `intlayerCompiler()` та `intlayerProxy()` залишаються експортованими для складних налаштувань. Реєстрація їх разом з `intlayer()` безпечна — кожен плагін автоматично дедублює себе і запускається лише один раз.
+
+---
+
 ## Примітки щодо міграції з v8
 
 Якщо ви оновлюєтеся з v8, зверніть увагу, що v9 не містить критичних змін (breaking changes). Проте ось ключові зміни:

package/docs/vi/autoFill.md

@@ -35,6 +35,26 @@ author: aymericzip
 
 **Các tệp khai báo nội dung tự động điền** trong CI của bạn là một cách để tăng tốc quy trình phát triển.
 
+## Hiểu về hành vi
+
+Lệnh `fill` bao gồm hai chế độ:
+
+- **Complete**: Tự động điền tất cả nội dung bị thiếu cho mỗi locale và chỉnh sửa tệp hiện tại hoặc tệp khác nếu được chỉ định. Nói cách khác, chế độ complete sẽ bỏ qua việc dịch nội dung hiện có nếu đã được dịch.
+- **Review**: Tự động điền **tất cả** nội dung cho mỗi locale và tạo cho một tệp cụ thể hoặc tệp khác nếu được chỉ định.
+
+Lệnh `fill` sẽ xử lý tất cả các tệp khai báo nội dung locale của bạn. Nói cách khác, nó sẽ không xử lý nội dung từ xa của bạn từ CMS. CMS bao gồm hệ thống quản lý bản dịch của riêng nó.
+Nếu bạn sử dụng các plugin như `@intlayer/sync-json-plugin`, Intlayer sẽ chuyển đổi các tệp JSON thành các tệp khai báo nội dung locale. Nói cách khác, chúng sẽ được xử lý bởi lệnh `fill`.
+
+Các tệp được tạo mới bao gồm một hướng dẫn `filled` như siêu dữ liệu từ điển. Hướng dẫn này sẽ được Intlayer sử dụng để biết liệu tệp đã được điền tự động hay không, và bỏ qua tệp này khỏi việc dịch lại nếu có.
+
+Intlayer cũng sẽ xem xét hướng dẫn sau để điền tự động:
+
+- Từ `.content.{ts|js|json}` của bạn → hướng dẫn `fill`
+- Từ tệp cấu hình `.intlayer.config.ts` của bạn → hướng dẫn `dictionary.fill`
+- Sẽ được đặt thành `true` theo mặc định nếu không có
+
+Đối với các tệp khai báo nội dung theo locale, hướng dẫn `true` sẽ được thay thế bằng `./{{fileName}}.fill.content.json`. Điều này là vì một tệp khai báo nội dung theo locale không thể nhận nội dung bản địa hóa bổ sung. Vì vậy, nó sẽ tạo một tệp mới để không ghi đè tệp hiện có.
+
 ## Hành Vi Mặc Định
 
 Theo mặc định, `fill` được đặt là `true` toàn cục, có nghĩa là Intlayer sẽ tự động điền tất cả các tệp nội dung và chỉnh sửa chính tệp đó. Hành vi này có thể được tùy chỉnh theo nhiều cách:

package/docs/vi/benchmark/solid.md

@@ -118,6 +118,28 @@ Chúng tôi đã so sánh **bốn chiến lược tải**:
 - **Scoped static**: Giữ cho mã được tổ chức (tách biệt logic) mà không cần các request mạng bổ sung phức tạp.
 - **Scoped dynamic**: Phương pháp tốt nhất cho _code splitting_ và hiệu suất. Giảm thiểu bộ nhớ bằng cách chỉ tải những gì chế độ xem hiện tại và ngôn ngữ đang hoạt động cần.
 
+### Những gì tôi đo lường:
+
+Tôi chạy cùng một ứng dụng đa ngôn ngữ trong trình duyệt thực tế cho mỗi stack, sau đó ghi lại những gì thực sự xuất hiện trên dây và mất bao lâu. Kích thước được báo cáo **sau nén web bình thường**, vì điều đó gần hơn với những gì mọi người tải xuống so với số lượng nguồn thô.
+
+- **Kích thước thư viện quốc tế hóa**: Sau khi bundling, tree-shaking và minification, kích thước của thư viện i18n là kích thước của providers + hooks/primitives code trong một thành phần rỗng. Nó không bao gồm việc tải các tệp dịch. Nó trả lời câu hỏi thư viện này tốn kém bao nhiêu trước khi nội dung của bạn xuất hiện.
+
+- **JavaScript trên mỗi trang**: Đối với mỗi tuyến đường benchmark, trình duyệt tải bao nhiêu script trong lần truy cập đó, trung bình trên các trang trong bộ (và trên các locale nếu báo cáo gộp chúng). Các trang nặng là các trang chậm.
+
+- **Rò rỉ từ các locale khác**: Đó là nội dung của cùng một trang nhưng bằng ngôn ngữ khác sẽ được tải do lỗi trong trang được kiểm tra. Nội dung này là không cần thiết và nên tránh. (ví dụ: nội dung trang `/fr/about` trong bundle trang `/en/about`)
+
+- **Rò rỉ từ các tuyến đường khác**: Ý tưởng tương tự cho **các màn hình khác** trong ứng dụng: liệu bản sao của chúng có đi kèm khi bạn chỉ mở một trang. (ví dụ: nội dung trang `/en/about` trong bundle trang `/en/contact`). Điểm số cao gợi ý splitting yếu hoặc bundles quá rộng.
+
+- **Kích thước bundle thành phần trung bình**: Các phần UI phổ biến được đo lường **từng cái một** thay vì ẩn trong một số ứng dụng khổng lồ. Nó cho thấy liệu quốc tế hóa có yên tĩnh làm tăng các thành phần hàng ngày hay không. Ví dụ, nếu thành phần của bạn render lại, nó sẽ tải tất cả dữ liệu đó từ bộ nhớ. Gắn một JSON khổng lồ vào bất kỳ thành phần nào cũng giống như kết nối một cửa hàng lớn dữ liệu không được sử dụng sẽ làm chậm hiệu suất các thành phần của bạn.
+
+- **Độ phản hồi chuyển đổi ngôn ngữ**: Tôi chuyển đổi ngôn ngữ bằng cách điều khiển của ứng dụng và đo lường thời gian cho đến khi trang đã rõ ràng chuyển đổi, điều mà một khách truy cập sẽ nhận thấy, không phải một bước micro trong phòng thí nghiệm.
+
+- **Rendering work sau khi thay đổi ngôn ngữ**: Một bước theo dõi hẹp hơn: giao diện tốn bao nhiêu công sức để vẽ lại cho ngôn ngữ mới khi việc chuyển đổi đang diễn ra. Hữu ích khi "cảm nhận" thời gian và chi phí framework khác nhau.
+
+- **Thời gian tải trang ban đầu**: Từ điều hướng đến trình duyệt coi trang được tải hoàn toàn cho các kịch bản tôi đã kiểm tra. Tốt cho so sánh các lần khởi động lạnh.
+
+- **Hydration time**: Khi ứng dụng cung cấp nó, trình duyệt máy khách dành bao lâu để biến HTML máy chủ thành thứ gì đó bạn thực sự có thể nhấp vào. Một dấu gạch ngang trong các bảng có nghĩa là việc thực hiện này không cung cấp một con số hydration đáng tin cậy trong benchmark này.
+
 ## Sao GitHub
 
 Sao GitHub là một chỉ số mạnh mẽ về mức độ phổ biến của dự án, sự tin tưởng của cộng đồng và mức độ phù hợp lâu dài. Mặc dù không phải là thước đo trực tiếp về chất lượng kỹ thuật, chúng phản ánh số lượng nhà phát triển thấy dự án hữu ích, theo dõi tiến trình của nó và có khả năng áp dụng nó. Để ước tính giá trị của một dự án, các ngôi sao giúp so sánh sức hút giữa các lựa chọn thay thế và cung cấp thông tin chi tiết về sự phát triển của hệ sinh thái.

package/docs/vi/benchmark/svelte.md

@@ -116,6 +116,28 @@ Chúng tôi đã so sánh **bốn chiến lược tải**:
 - **Scoped static**: Giữ cho mã được tổ chức (tách biệt logic) mà không cần các request mạng bổ sung phức tạp.
 - **Scoped dynamic**: Phương pháp tốt nhất cho _code splitting_ và hiệu suất. Giảm thiểu bộ nhớ bằng cách chỉ tải những gì chế độ xem hiện tại và ngôn ngữ đang hoạt động cần.
 
+### Những gì tôi đo lường:
+
+Tôi đã chạy cùng một ứng dụng đa ngôn ngữ trong trình duyệt thực tế cho mọi stack, sau đó ghi lại những gì thực sự xuất hiện trên đường truyền và mất bao lâu. Kích thước được báo cáo **sau khi nén web bình thường**, bởi vì điều đó gần hơn với những gì mọi người tải xuống so với số lượng nguồn thô.
+
+- **Kích thước thư viện quốc tế hóa**: Sau khi bundle, tree-shaking và minification, kích thước của thư viện i18n là kích thước của mã providers + stores trong một component trống. Nó không bao gồm việc tải các tệp dịch. Nó trả lời câu hỏi thư viện tốn kém bao nhiêu trước khi nội dung của bạn vào tranh.
+
+- **JavaScript trên mỗi trang**: Đối với mỗi tuyến benchmark, trình duyệt kéo bao nhiêu script trong lần truy cập đó, được tính trung bình trên các trang trong bộ (và trên các locale khi báo cáo tập hợp chúng). Các trang nặng là các trang chậm.
+
+- **Rò rỉ từ các locale khác**: Đó là nội dung của cùng một trang nhưng ở ngôn ngữ khác sẽ được tải nhầm trong trang đã kiểm toán. Nội dung này là không cần thiết và nên được tránh. (ví dụ: nội dung trang `/fr/about` trong bundle trang `/en/about`)
+
+- **Rò rỉ từ các tuyến khác**: Cùng ý tưởng cho **các màn hình khác** trong ứng dụng: liệu bản sao của chúng có được đi cùng khi bạn chỉ mở một trang. (ví dụ: nội dung trang `/en/about` trong bundle trang `/en/contact`). Điểm số cao gợi ý về splitting yếu hoặc các bundle quá rộng.
+
+- **Kích thước bundle component trung bình**: Các phần giao diện người dùng phổ biến được đo **một lần** thay vì ẩn bên trong một con số ứng dụng khổng lồ. Nó cho thấy liệu quốc tế hóa có im lặng làm tăng các component hàng ngày hay không. Ví dụ, nếu component của bạn render lại, nó sẽ tải tất cả dữ liệu đó từ bộ nhớ. Đính kèm một JSON khổng lồ vào bất kỳ component nào giống như kết nối một kho dữ liệu không sử dụng lớn sẽ làm chậm hiệu suất của các component của bạn.
+
+- **Khảp phản ứng chuyển đổi ngôn ngữ**: Tôi lật ngôn ngữ bằng cách điều khiển của ứng dụng và đo thời gian cho đến khi trang rõ ràng đã chuyển đổi, điều mà một người truy cập sẽ nhận thấy, không phải một bước vi mô trong phòng thí nghiệm.
+
+- **Công việc rendering sau khi thay đổi ngôn ngữ**: Một bước theo dõi hẹp hơn: giao diện tốn bao nhiêu nỗ lực để vẽ lại cho ngôn ngữ mới khi công tắc đang diễn ra. Hữu ích khi thời gian "cảm nhận" và chi phí framework khác nhau.
+
+- **Thời gian tải trang ban đầu**: Từ điều hướng đến trình duyệt xem xét trang được tải hoàn toàn cho các kịch bản tôi đã kiểm tra. Tốt cho việc so sánh khởi động lạnh.
+
+- **Thời gian hydration**: Khi ứng dụng hiển thị, người dùng khách hàng dành bao lâu để biến HTML máy chủ thành thứ bạn thực sự có thể nhấp vào. Dấu gạch ngang trong các bảng có nghĩa là triển khai đó không cung cấp hình hydration đáng tin cậy trong benchmark này.
+
 ## Sao GitHub
 
 Sao GitHub là một chỉ số mạnh mẽ về mức độ phổ biến của dự án, sự tin tưởng của cộng đồng và mức độ phù hợp lâu dài. Mặc dù không phải là thước đo trực tiếp về chất lượng kỹ thuật, chúng phản ánh số lượng nhà phát triển thấy dự án hữu ích, theo dõi tiến trình của nó và có khả năng áp dụng nó. Để ước tính giá trị của một dự án, các ngôi sao giúp so sánh sức hút giữa các lựa chọn thay thế và cung cấp thông tin chi tiết về sự phát triển của hệ sinh thái.

package/docs/vi/benchmark/tanstack.md

@@ -124,6 +124,28 @@ Chúng tôi đã so sánh **bốn chiến lược tải**:
 - **Scoped static**: Giữ cho mã được tổ chức (tách biệt logic) mà không cần các yêu cầu mạng bổ sung phức tạp.
 - **Scoped dynamic**: Phương pháp tốt nhất cho việc _chia tách mã_ (code splitting) và hiệu năng. Giảm thiểu bộ nhớ bằng cách chỉ tải những gì cần thiết cho chế độ xem hiện tại và ngôn ngữ đang hoạt động.
 
+### Những gì tôi đã đo lường:
+
+Tôi chạy cùng một ứng dụng đa ngôn ngữ trong một trình duyệt thực cho mỗi stack, sau đó ghi lại những gì thực sự xuất hiện trên đường truyền và mất bao lâu. Kích thước được báo cáo **sau nén web bình thường**, bởi vì điều đó gần hơn với những gì mọi người tải xuống so với số lượng nguồn thô.
+
+- **Kích thước thư viện quốc tế hóa**: Sau khi bundling, tree-shaking và minification, kích thước của thư viện i18n là kích thước của các providers (ví dụ: `NextIntlClientProvider`) + hooks (ví dụ: `useTranslations`) code trong một component trống. Nó không bao gồm việc tải các tệp dịch. Nó trả lời câu hỏi thư viện tốn kém bao nhiêu trước khi nội dung của bạn vào vào hình ảnh.
+
+- **JavaScript trên mỗi trang**: Đối với mỗi tuyến đường benchmark, trình duyệt tải bao nhiêu script trong lần truy cập đó, được tính trung bình trên các trang trong bộ (và trên các locales nơi báo cáo ghi chép chúng). Các trang nặng là các trang chậm.
+
+- **Rò rỉ từ các locales khác**: Đó là nội dung của cùng một trang nhưng ở ngôn ngữ khác sẽ được tải bởi lỗi trên trang được kiểm tra. Nội dung này là không cần thiết và nên tránh. (ví dụ: nội dung trang `/fr/about` trong bundle trang `/en/about`)
+
+- **Rò rỉ từ các tuyến đường khác**: Cùng ý tưởng cho **các màn hình khác** trong ứng dụng: liệu bản sao của chúng có đi cùng khi bạn chỉ mở một trang. (ví dụ: nội dung trang `/en/about` trong bundle trang `/en/contact`). Điểm số cao gợi ý tách biệt yếu hoặc bundle quá rộng.
+
+- **Kích thước bundle component trung bình**: Các UI pieces phổ biến được đo lường **từng cái một** thay vì ẩn bên trong một số ứng dụng khổng lồ. Nó cho thấy liệu quốc tế hóa có yên tĩnh làm tăng các component hàng ngày hay không. Ví dụ, nếu component của bạn renders lại, nó sẽ tải tất cả dữ liệu đó từ bộ nhớ. Gắn một JSON lớn vào bất kỳ component nào cũng giống như kết nối một cửa hàng lớn dữ liệu không sử dụng sẽ làm chậm hiệu suất component của bạn.
+
+- **Khả năng phản hồi khi chuyển đổi ngôn ngữ**: Tôi lật ngôn ngữ bằng cách sử dụng điều khiển của ứng dụng và đo thời gian cần thiết cho đến khi trang đã rõ ràng được chuyển đổi, điều mà một khách truy cập sẽ nhận thấy, không phải một bước micro của phòng thí nghiệm.
+
+- **Công việc rendering sau khi thay đổi ngôn ngữ**: Một lần theo dõi hẹp hơn: giao diện mất bao nhiêu nỗ lực để vẽ lại cho ngôn ngữ mới khi sự chuyển đổi đang được thực hiện. Hữu ích khi thời gian "cảm nhận" và chi phí framework phân kỳ.
+
+- **Thời gian tải trang ban đầu**: Từ điều hướng đến trình duyệt xem xét trang được tải đầy đủ cho các kịch bản tôi đã kiểm tra. Tốt để so sánh lần khởi động lạnh.
+
+- **Thời gian hydration**: Khi ứng dụng hiển thị nó, khách hàng mất bao lâu để biến HTML máy chủ thành thứ bạn thực sự có thể nhấp. Một dấu gạch ngang trong các bảng có nghĩa là việc triển khai này không cung cấp con số hydration đáng tin cậy trong benchmark này.
+
 ## Sao GitHub
 
 Sao GitHub là một chỉ số mạnh mẽ về mức độ phổ biến của dự án, sự tin tưởng của cộng đồng và mức độ phù hợp lâu dài. Mặc dù không phải là thước đo trực tiếp về chất lượng kỹ thuật, chúng phản ánh số lượng nhà phát triển thấy dự án hữu ích, theo dõi tiến trình của nó và có khả năng áp dụng nó. Để ước tính giá trị của một dự án, các ngôi sao giúp so sánh sức hút giữa các lựa chọn thay thế và cung cấp thông tin chi tiết về sự phát triển của hệ sinh thái.

package/docs/vi/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## GitHub Actions được tạo tự động
+
+Khi bạn chạy `intlayer init`, Intlayer sẽ phát hiện package manager của bạn (npm, yarn, pnpm, hoặc bun) và tạo hai workflow GitHub Actions trong `.github/workflows/`, với các lệnh phù hợp với package manager đó:
+
+- **`intlayer-fill.yml`** — Trên mọi pull request, xây dựng các từ điển và chạy `intlayer fill --git-diff --mode complete` để tạo các bản dịch bị thiếu cho các từ điển đã thay đổi, sau đó commit kết quả lại vào nhánh PR.
+- **`intlayer-test.yml`** — Trên mọi pull request, xây dựng các từ điển và chạy `intlayer test`, làm cho kiểm tra thất bại khi các locale bắt buộc bị thiếu bản dịch.
+
+Các tập tin workflow hiện có sẽ không bao giờ bị ghi đè. Để bỏ qua việc tạo tự động hoàn toàn, hãy chạy:
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### Cấp quyền truy cập AI cho quy trình fill
+
+`intlayer-fill.yml` được tạo ra yêu cầu quyền truy cập AI. Có hai tùy chọn có sẵn (được cấu hình trong khối `env` của quy trình):
+
+1. **Khóa nhà cung cấp AI của riêng bạn** — Thêm bí mật `AI_API_KEY` trong cài đặt kho lưu trữ của bạn (Settings → Secrets and variables → Actions). Quy trình sẽ chuyển tiếp nó qua `--provider`, `--model` và `--api-key`.
+2. **Khóa truy cập Intlayer CMS** — Thêm bí mật `INTLAYER_CLIENT_ID` và `INTLAYER_CLIENT_SECRET` và kết nối chúng vào phần `editor` của `intlayer.config` của bạn. Các khóa truy cập CMS cấp quyền truy cập AI thông qua backend Intlayer.
+
+Quy trình `intlayer-test.yml` không yêu cầu bất kỳ quyền truy cập AI nào.
+
 ## Xử lý lỗi
 
 - Nếu `INTLAYER_PROJECT_CREDENTIALS` không được đặt, lệnh sẽ thoát với lỗi.

package/docs/vi/cli/fill.md

@@ -47,6 +47,14 @@ Lệnh này phân tích các tệp khai báo nội dung của bạn để tìm c
 - Bảo tồn các bản dịch hiện có bằng cách không ghi đè chúng.
 - Xử lý tệp, phần và ngôn ngữ song song bằng hệ thống hàng đợi để tăng tốc độ.
 
+## Những Điểm Chính:
+
+- Chia các tệp JSON lớn thành các chunks để duy trì trong giới hạn cửa sổ ngữ cảnh của mô hình AI.
+- Thử lại dịch nếu định dạng đầu ra không chính xác.
+- Kết hợp ngữ cảnh cụ thể cho ứng dụng và tệp để cải thiện độ chính xác của bản dịch.
+- Bảo tồn các bản dịch hiện có bằng cách không ghi đè chúng.
+- Xử lý các tệp, chunks và locales song song bằng cách sử dụng hệ thống queue để tăng tốc độ.
+
 ## Bí danh:
 
 - `npx intlayer dictionaries fill`

package/docs/vi/cli/login.md

@@ -78,42 +78,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 ### Tùy chọn cấu hình
 
-Bạn cũng có thể sử dụng các tùy chọn cấu hình chung sau:
-
-- `--env-file <path>`: Đường dẫn tới file môi trường
-- `-e, --env <env>`: Môi trường thực thi
-- `--base-dir <dir>`: Thư mục gốc của dự án
-- `--verbose`: Bật đầu ra chi tiết (mặc định: true)
-- `--prefix <prefix>`: Tiền tố cho logs
-
-## Cách hoạt động
-
-1. **Khởi động máy chủ cục bộ**: Lệnh khởi động một máy chủ HTTP cục bộ trên một cổng ngẫu nhiên để nhận thông tin xác thực từ CMS
-
-Chỉ định URL của Intlayer CMS để kết nối xác thực.
-
-- **Loại**: `string`
-- **Mặc định**: Giá trị được cấu hình trong `intlayer.config.*` hoặc `https://intlayer.org`
-- **Ví dụ**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### Tùy chọn cấu hình
-
 Bạn cũng có thể sử dụng các tùy chọn cấu hình chung:
 
 - `--env-file <path>`: Đường dẫn tới file môi trường

package/docs/vi/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Di Chuyển Từ i18n-js Sang Intlayer"
+description: "Tìm hiểu cách di chuyển ứng dụng của bạn từ i18n-js sang Intlayer bằng bộ điều hợp tương thích."
+keywords:
+  - i18n-js
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Di Chuyển Từ i18n-js Sang Intlayer
+
+Việc chuyển đổi từ thư viện `i18n-js` sang Intlayer là một quá trình di chuyển được tối ưu hóa cao, được thiết kế để chuyển các cấu hình dịch thuật lớn sang hệ thống phân giải file có cấu trúc của Intlayer.
+
+## Phải làm gì
+
+Thực thi lệnh thiết lập sau trong repository của bạn:
+
+```bash
+npx intlayer init
+```
+
+Sau khi `intlayer.config.ts` được chuẩn bị, bạn có thể thêm bí danh của Intlayer vào cấu hình bundler của mình để bất kỳ import nào của `i18n-js` đều trỏ đến gói tương thích `@intlayer/i18n-js`.
+
+## Những gì diễn ra bên dưới
+
+`i18n-js` truy cập các namespace thông qua các biểu thức như `i18n.t('scope.key', {name})` cùng với các cơ chế dự phòng theo ngôn ngữ và ánh xạ số nhiều cụ thể.
+
+Bên dưới:
+
+- **Nội suy:** Bộ điều hợp tương thích dễ dàng phân tích các ánh xạ `%{name}` thành giá trị từ điển đích tại thời điểm chạy.
+- **Số nhiều:** Thay thế các subkey `one/other` và ánh xạ chúng sang các cơ chế số nhiều mạnh mẽ của Intlayer (`Intl.PluralRules`), loại bỏ các ánh xạ thủ công.
+- **Ngôn ngữ:** Thay vì tải toàn bộ payload ngôn ngữ khi khởi động, các từ điển được phục vụ tối ưu dựa trên thiết lập ngữ cảnh hiện tại thông qua cấu hình Intlayer gốc.

package/docs/vi/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Di Chuyển Từ i18next Sang Intlayer"
+description: "Tìm hiểu cách di chuyển ứng dụng Vanilla JS/TS của bạn từ i18next sang Intlayer bằng bộ điều hợp tương thích."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Di Chuyển Từ i18next Sang Intlayer
+
+Để có hướng dẫn từng bước chi tiết, vui lòng xem [Hướng Dẫn Di Chuyển i18next](../migration_from_i18next_to_intlayer.md) đầy đủ của chúng tôi.
+
+Intlayer tái tạo hoàn hảo các đặc tính runtime cốt lõi của `i18next`. Bằng cách sử dụng gói tương thích, các ứng dụng Vanilla hoặc các module nội bộ của bạn có thể tiếp tục tận dụng cú pháp quen thuộc.
+
+## Phải làm gì
+
+Để bắt đầu, hãy khởi tạo Intlayer trong dự án của bạn:
+
+```bash
+npx intlayer init
+```
+
+Nếu bạn đang sử dụng Vite, hãy bao gồm plugin Intlayer để định tuyến các import sang `@intlayer/i18next`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## Những gì diễn ra bên dưới
+
+`i18nextVitePlugin` tạo bí danh cho các import `i18next` sang `@intlayer/i18next`, tránh việc bundle bị phình to do bao gồm các file JSON.
+
+Bên dưới:
+
+- **Cấu hình instance:** `createInstance` phân tích chính xác và áp dụng các namespace fallback trong khi tận dụng pipeline biên dịch của Intlayer để truy xuất từ điển.
+- **Nội suy:** Hỗ trợ gốc cho các thay thế `{{name}}` và lồng `$t(key)` theo đệ quy.
+- **Ngữ cảnh & Số nhiều:** Xác định và giải quyết các định dạng hậu tố như `key_male` và `key_one`/`key_other` đánh giá dựa trên `Intl.PluralRules` tiêu chuẩn.
+- **Trả về đối tượng:** Chế độ `returnObjects: true` an toàn trích xuất cây từ các từ điển Intlayer.

package/docs/vi/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Bộ Điều Hợp Tương Thích Intlayer"
+description: "Di chuyển giải pháp i18n hiện có của bạn sang Intlayer một cách dễ dàng bằng các bộ điều hợp tương thích."
+keywords:
+  - compat
+  - migration
+  - internationalization
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Bộ Điều Hợp Tương Thích Intlayer
+
+Việc di chuyển một ứng dụng lớn sang thư viện quốc tế hóa mới có thể là một thách thức lớn. Để giảm bớt quá trình chuyển đổi này, Intlayer cung cấp **các bộ điều hợp tương thích** cho các thư viện i18n phổ biến nhất trong hệ sinh thái.
+
+Các gói điều hợp này cung cấp **chính xác cùng một API công khai** như các thư viện i18n hiện có của bạn, nhưng ủy thác toàn bộ công việc dịch thuật cho Intlayer tại thời điểm chạy.
+
+## Cách hoạt động
+
+Khi bạn sử dụng một bộ điều hợp tương thích, bạn không cần phải viết lại các lệnh import trong ứng dụng hoặc thay đổi cách bạn sử dụng các hook và component dịch thuật. Thay vào đó, các plugin bundler của Intlayer tự động tạo bí danh cho các import hiện có của bạn sang các gói tương thích Intlayer.
+
+Ví dụ, một nhà phát triển thay thế `import { useTranslation } from 'react-i18next'` bằng `import { useTranslation } from '@intlayer/react-i18next'` (được thực hiện tự động thông qua plugin bundler), và ứng dụng tiếp tục hoạt động với các bản dịch nay được cung cấp từ từ điển Intlayer. Các key cũng được đánh kiểu dựa trên từ điển Intlayer của bạn!
+
+## Các Bộ Điều Hợp Tương Thích Có Sẵn
+
+Chọn thư viện hiện có của bạn bên dưới để xem cách di chuyển một cách liền mạch:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/vi/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Di Chuyển Từ Lingui Sang Intlayer"
+description: "Tìm hiểu cách di chuyển ứng dụng của bạn từ Lingui sang Intlayer bằng bộ điều hợp tương thích."
+keywords:
+  - lingui
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Di Chuyển Từ Lingui Sang Intlayer
+
+Nếu dự án của bạn hiện đang sử dụng quá trình biên dịch dựa trên macro của Lingui, việc chuyển đổi sang Intlayer cho phép bạn duy trì các quy trình macro mạnh mẽ trong khi hỗ trợ chúng một cách gốc với chiến lược biên dịch JSON của Intlayer.
+
+## Phải làm gì
+
+Để bắt đầu, hãy khởi tạo Intlayer trong dự án của bạn:
+
+```bash
+npx intlayer init
+```
+
+Lệnh này tạo `intlayer.config.ts` của bạn. Đảm bảo giữ lại `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` trong bước build để chạy _trước_ trình biên dịch Intlayer. Sau đó, sử dụng bí danh plugin bundler để định tuyến `@lingui/core` và `@lingui/react` sang `@intlayer/lingui`.
+
+## Những gì diễn ra bên dưới
+
+Lingui sử dụng các macro (như `` t`Hello ${name}` `` và `<Trans>`) được biên dịch thành các lời gọi runtime như `i18n._(id, values)`.
+
+Bên dưới:
+
+- **Macro:** Chúng biên dịch chính xác như trước đây, đảm bảo không có sự gián đoạn trong cú pháp nguồn của bạn.
+- **Dịch thuật tại runtime:** `i18n._()` được đặt bí danh sử dụng các từ điển Intlayer. Cả ID được đặt tên rõ ràng và ID được băm đều được ánh xạ đầy đủ bằng cách sử dụng các plugin đồng bộ `.po` của Intlayer để tổng hợp và loại bỏ các key một cách an toàn.
+- **Khả năng ICU:** Hỗ trợ số nhiều, lựa chọn và các biến thể ICU vẫn mạnh mẽ nhờ trình phân tích ICU thống nhất của Intlayer, đảm bảo đầu ra hiển thị giống nhau.

package/docs/vi/compat/next-i18next.md

@@ -0,0 +1,57 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Di Chuyển Từ next-i18next Sang Intlayer"
+description: "Tìm hiểu cách di chuyển ứng dụng Next.js của bạn từ next-i18next sang Intlayer bằng bộ điều hợp tương thích."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Di Chuyển Từ next-i18next Sang Intlayer
+
+Để có hướng dẫn từng bước đầy đủ và chi tiết, vui lòng xem [Hướng Dẫn Di Chuyển next-i18next](../migration_from_next-i18next_to_intlayer.md) đầy đủ của chúng tôi.
+
+Intlayer xử lý tất cả các triển khai Next.js Pages Router và App Router một cách minh bạch. Sử dụng bộ điều hợp cho phép bạn di chuyển triển khai `next-i18next` mà không cần viết lại bất kỳ code nào.
+
+## Phải làm gì
+
+Để bắt đầu, hãy chạy:
+
+```bash
+npx intlayer init
+```
+
+Lệnh này tạo file thiết lập Intlayer cần thiết. Để chuyển sang Intlayer ở hậu trường, hãy cập nhật `next.config.ts` của bạn:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## Những gì diễn ra bên dưới
+
+`createNextI18nPlugin` kết hợp hành vi gốc của Next.js cùng với plugin `next-intlayer` cốt lõi, chèn tất cả các bí danh Webpack/Turbopack cần thiết cho `next-i18next`, `react-i18next` và `i18next`.
+
+Bên dưới:
+
+- **`serverSideTranslations` & `appWithTranslation`:** Chúng hiện hoạt động như các wrapper cho các bộ tải nội bộ của Intlayer, bỏ qua việc chèn JSON tĩnh lớn.
+- **Hook phía client:** Ủy thác ngay lập tức cho `@intlayer/react-i18next`, giữ lại tất cả các tính năng định dạng, số nhiều và namespace lồng nhau.

package/docs/vi/compat/next-intl.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Di Chuyển Từ next-intl Sang Intlayer"
+description: "Tìm hiểu cách di chuyển ứng dụng Next.js của bạn từ next-intl sang Intlayer bằng bộ điều hợp tương thích."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Di Chuyển Từ next-intl Sang Intlayer
+
+Để có hướng dẫn từng bước đầy đủ và chi tiết, vui lòng xem [Hướng Dẫn Di Chuyển next-intl](../migration_from_next-intl_to_intlayer.md) đầy đủ của chúng tôi.
+
+Việc di chuyển từ `next-intl` sang Intlayer cho phép bạn duy trì routing và cú pháp của ứng dụng hoàn toàn không bị gián đoạn.
+
+## Phải làm gì
+
+Thực thi lệnh sau trong repository của bạn:
+
+```bash
+npx intlayer init
+```
+
+Lệnh này sẽ tạo một `intlayer.config.ts`. Trong `next.config.ts` của bạn, hãy sử dụng wrapper plugin để liền mạch chèn các bí danh `next-intl` hướng đến `@intlayer/next-intl`.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## Những gì diễn ra bên dưới
+
+Wrapper bundler thay thế các bản dịch, nhưng **giữ nguyên các tính năng `next-intl/navigation`** (ví dụ: `Link`, `redirect`, `usePathname`).
+
+Bên dưới:
+
+- **Runtime ICU:** Số nhiều (`=0`, `one`, `other`), select/selectordinal, đối số `#` và các đối số được định dạng (`{ts, date, long}`) chạy chính xác bằng cách sử dụng resolver `resolveMessage(..., 'icu')` được chia sẻ.
+- **`useTranslations()` & `getTranslations()`:** Các lời gọi phạm vi đơn giản trích xuất đoạn key đầu tiên làm định danh từ điển chính xác. Các namespace lồng nhau được tách một cách uyển chuyển thành các đường dẫn từ điển và tiền tố.
+- **Định dạng phong phú:** Cả `t.rich()` và `t.markup()` đều được triển khai gốc đầy đủ, chuyển đổi các nút dạng HTML thành các chunk React được hiển thị.
+- **`useFormatter`:** `relativeTime`, `list`, `dateTimeRange` và các định dạng được đặt tên từ cấu hình kết nối với các formatter `Intl` gốc của core.

package/docs/vi/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Di Chuyển Từ Next Translate Sang Intlayer"
+description: "Tìm hiểu cách di chuyển ứng dụng Next.js của bạn từ next-translate sang Intlayer bằng bộ điều hợp tương thích."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Di Chuyển Từ Next Translate Sang Intlayer
+
+Việc di chuyển từ `next-translate` sang Intlayer gần như là một sự thay thế hoàn toàn, giữ lại cú pháp và các thẻ hiện có của bạn.
+
+## Phải làm gì
+
+Khởi tạo Intlayer trong dự án của bạn:
+
+```bash
+npx intlayer init
+```
+
+CLI sẽ tạo cấu hình của bạn. Sau đó bạn có thể áp dụng plugin Intlayer trong `next.config.ts` của mình, plugin này chèn các bí danh subpath tại thời điểm build ánh xạ `next-translate/useTranslation` sang `@intlayer/next-translate`.
+
+## Những gì diễn ra bên dưới
+
+`next-translate` cung cấp các hook như `useTranslation('ns')`, `t('ns:key.path')` và component `<Trans>`.
+
+Bên dưới:
+
+- **Nội suy & Số nhiều:** Nó phụ thuộc chặt chẽ vào hành vi của bộ điều hợp `react-i18next`. Các placeholder `{{var}}` và số nhiều được ánh xạ từ các hậu tố như `key_0`, `key_one` và `key_other` được xử lý động.
+- **Component `<Trans>`:** Được hỗ trợ trực tiếp cho việc phân tích thẻ dạng HTML cùng với prop `components` dựa trên mảng.
+- **Namespace:** Việc đặt bí danh subpath đảm bảo rằng `useTranslation` của bạn tham chiếu đúng namespace từ điển nội bộ mà không cần sửa đổi thủ công.