@intlayer/docs 7.2.3 → 7.3.0

package/docs/vi/cli/test.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Kiểm tra bản dịch thiếu
+description: Tìm hiểu cách kiểm tra và xác định các bản dịch thiếu trong từ điển của bạn.
+keywords:
+  - Kiểm tra
+  - Bản dịch thiếu
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - test
+---
+
+# Kiểm tra bản dịch thiếu
+
+```bash
+npx intlayer content test
+```
+
+## Bí danh:
+
+- `npx intlayer test`
+
+Lệnh này phân tích các tệp khai báo nội dung của bạn để xác định các bản dịch thiếu trên tất cả các locale đã cấu hình. Nó cung cấp một báo cáo toàn diện cho thấy các khóa dịch nào đang thiếu ở các locale nào, giúp bạn duy trì sự nhất quán trong nội dung đa ngôn ngữ của mình.
+
+## Ví dụ đầu ra:
+
+```bash
+pnpm intlayer content test
+Missing translations:
+ - home-page                      - tr         - src/components/HomePage/homePage.content.ts
+ - server-component               - es, tr     - src/components/ServerComponent/serverComponent.content.ts
+ - client-component               - pl, tr     - src/components/ClientComponent/clientComponent.content.ts
+Locales: en, ru, ja, fr, ko, zh, es, de, ar, it, en-GB, pt, hi, tr, pl
+Required locales: en
+Missing locales: pl, tr, es
+Missing required locales: -
+Total missing locales: 3
+Total missing required locales: 0
+```
+
+## Tham số:
+
+**Tùy chọn cấu hình:**
+
+- **`--env`**: Chỉ định môi trường (ví dụ: `development`, `production`).
+- **`--env-file [envFile]`**: Cung cấp tệp môi trường tùy chỉnh để tải biến.
+- **`--base-dir`**: Chỉ định thư mục gốc cho dự án.
+
+  > Ví dụ: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+- **`--no-cache`**: Vô hiệu hóa bộ nhớ đệm.
+
+  > Ví dụ: `npx intlayer build --no-cache`
+
+**Tùy chọn chuẩn bị:**
+
+- **`--build`**: Xây dựng các từ điển trước khi đẩy để đảm bảo nội dung được cập nhật. True sẽ bắt buộc xây dựng, false sẽ bỏ qua việc xây dựng, undefined sẽ cho phép sử dụng bộ nhớ đệm của bản xây dựng.
+
+**Tùy chọn ghi log:**
+
+- **`--verbose`**: Bật ghi log chi tiết để gỡ lỗi. (mặc định là true khi sử dụng CLI)
+
+  > Ví dụ: `npx intlayer content test --verbose`
+
+## Ví dụ:
+
+```bash
+npx intlayer content test --verbose
+```
+
+Kết quả đầu ra giúp bạn nhanh chóng xác định các bản dịch cần được hoàn thành để đảm bảo ứng dụng của bạn hoạt động đúng trên tất cả các locale đã cấu hình.

package/docs/vi/cli/transform.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Chuyển đổi Components
+description: Tìm hiểu cách chuyển đổi các component hiện có để sử dụng Intlayer.
+keywords:
+  - Chuyển đổi
+  - Components
+  - Di cư
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - transform
+---
+
+# Chuyển đổi components
+
+```bash
+npx intlayer transform
+```
+
+Lệnh này phân tích các file mã của bạn để hỗ trợ di cư các component hiện có sang sử dụng Intlayer. Nó hỗ trợ lựa chọn file tương tác hoặc chỉ định file cụ thể để chuyển đổi.
+
+## Bí danh:
+
+- `npx intlayer trans`
+
+## Tham số:
+
+**Tùy chọn chọn file:**
+
+- **`-f, --file [files...]`**: Danh sách các file cụ thể để chuyển đổi. Nếu không được cung cấp, CLI sẽ quét các file phù hợp (`**/*.{tsx,jsx,vue,svelte,ts,js}`) và yêu cầu bạn chọn những file nào để chuyển đổi.
+
+  > Ví dụ: `npx intlayer transform -f src/components/MyComponent.tsx`
+
+**Tùy chọn đầu ra:**
+
+- **`-o, --output-content-declarations [outputContentDeclarations]`**: Thư mục để lưu các file khai báo nội dung được tạo ra.
+
+  > Ví dụ: `npx intlayer transform -o src/content`
+
+- **`--code-only`**: Chỉ chuyển đổi mã component (không ghi khai báo nội dung).
+
+  > Ví dụ: `npx intlayer transform --code-only`
+
+- **`--declaration-only`**: Chỉ tạo khai báo nội dung (không viết lại component).
+
+  > Ví dụ: `npx intlayer transform --declaration-only`
+
+**Tùy chọn cấu hình:**
+
+- **`--base-dir`**: Chỉ định thư mục gốc cho dự án.
+- **`--env`**: Chỉ định môi trường.
+- **`--env-file`**: Cung cấp file môi trường tùy chỉnh.
+- **`--verbose`**: Bật ghi log chi tiết.
+
+**Các plugin cần thiết:**
+
+Lệnh transform hoạt động mà không cần plugin bổ sung trên các file TypeScript / JSX. Tuy nhiên, nó yêu cầu cài đặt các plugin sau cho các dự án Vue và Svelte:
+
+- **`@intlayer/vue-transformer`**: Dành cho các file Vue.
+- **`@intlayer/svelte-transformer`**: Dành cho các file Svelte.

package/docs/vi/cli/version.md

@@ -0,0 +1,24 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Kiểm tra phiên bản CLI
+description: Tìm hiểu cách kiểm tra phiên bản Intlayer CLI đã được cài đặt.
+keywords:
+  - Phiên bản
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - version
+---
+
+# Kiểm tra phiên bản CLI
+
+```bash
+npx intlayer --version
+npx intlayer version
+```
+
+Cả hai lệnh đều in ra phiên bản Intlayer CLI đã được cài đặt.

package/docs/vi/cli/watch.md

@@ -0,0 +1,37 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Theo dõi Từ điển
+description: Tìm hiểu cách theo dõi các thay đổi trong các tệp khai báo nội dung của bạn và tự động xây dựng từ điển.
+keywords:
+  - Theo dõi
+  - Từ điển
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - watch
+---
+
+# Theo dõi Từ điển
+
+```bash
+npx intlayer watch
+```
+
+Lệnh này sẽ theo dõi các thay đổi trong các tệp khai báo nội dung của bạn và xây dựng các từ điển trong thư mục `.intlayer`.
+Lệnh này tương đương với `npx intlayer build --watch --skip-prepare`.
+
+## Các bí danh:
+
+- `npx intlayer dictionaries watch`
+- `npx intlayer dictionary watch`
+- `npx intlayer dic watch`
+
+## Tham số:
+
+- **`--with`**: Khởi chạy lệnh song song với việc theo dõi.
+
+> Ví dụ: `npx intlayer watch --with "next dev --turbopack"`

package/docs/vi/packages/intlayer/getPrefix.md

@@ -0,0 +1,213 @@
+---
+createdAt: 2025-11-16
+updatedAt: 2025-11-16
+title: Tài liệu hàm getPrefix | intlayer
+description: Xem cách sử dụng hàm getPrefix cho gói intlayer
+keywords:
+  - getPrefix
+  - prefix
+  - Intlayer
+  - intlayer
+  - Quốc tế hóa
+  - Tài liệu
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getPrefix
+history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: Tài liệu ban đầu
+---
+
+# Tài liệu: Hàm `getPrefix` trong `intlayer`
+
+## Mô tả
+
+Hàm `getPrefix` xác định tiền tố URL cho một locale nhất định dựa trên cấu hình chế độ định tuyến. Nó so sánh locale với locale mặc định và trả về một đối tượng chứa ba định dạng tiền tố khác nhau để xây dựng URL linh hoạt.
+
+**Tính năng chính:**
+
+- Nhận một locale làm tham số đầu tiên (bắt buộc)
+- Đối tượng `options` tùy chọn với `defaultLocale` và `mode`
+- Trả về một đối tượng với các thuộc tính `prefix` và `localePrefix`
+- Hỗ trợ tất cả các chế độ định tuyến: `prefix-no-default`, `prefix-all`, `no-prefix`, và `search-params`
+- Công cụ nhẹ để xác định khi nào cần thêm tiền tố locale
+
+---
+
+## Chữ ký hàm
+
+```typescript
+getPrefix(
+  locale: Locales,               // Bắt buộc
+  options?: {                    // Tùy chọn
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): GetPrefixResult
+
+type GetPrefixResult = {
+  prefix: string;   // ví dụ: 'fr/' hoặc ''
+  localePrefix?: Locale; // ví dụ: 'fr' hoặc undefined
+}
+```
+
+---
+
+## Tham số
+
+- `locale: Locales`
+  - **Mô tả**: Locale để tạo tiền tố. Nếu giá trị là falsy (undefined, null, chuỗi rỗng), hàm sẽ trả về chuỗi rỗng.
+  - **Kiểu**: `Locales`
+  - **Bắt buộc**: Có
+
+- `options?: object`
+  - **Mô tả**: Đối tượng cấu hình để xác định tiền tố.
+  - **Kiểu**: `object`
+  - **Bắt buộc**: Không (Tùy chọn)
+
+  - `options.defaultLocale?: Locales`
+    - **Mô tả**: Locale mặc định cho ứng dụng. Nếu không cung cấp, sẽ sử dụng locale mặc định được cấu hình trong cấu hình dự án của bạn.
+    - **Kiểu**: `Locales`
+    - **Mặc định**: [`Cấu hình dự án`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Mô tả**: Chế độ định tuyến URL cho việc xử lý locale. Nếu không được cung cấp, sẽ sử dụng chế độ đã cấu hình trong cấu hình dự án của bạn.
+    - **Kiểu**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Mặc định**: [`Cấu hình dự án`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md#middleware)
+    - **Chế độ**:
+      - `prefix-no-default`: Trả về chuỗi rỗng khi locale trùng với locale mặc định
+      - `prefix-all`: Trả về tiền tố cho tất cả các locale bao gồm cả mặc định
+      - `no-prefix`: Trả về chuỗi rỗng (không có tiền tố trong URL)
+      - `search-params`: Trả về chuỗi rỗng (locale trong tham số truy vấn)
+
+### Trả về
+
+- **Kiểu**: `GetPrefixResult`
+- **Mô tả**: Một đối tượng chứa ba định dạng tiền tố khác nhau:
+  - `prefix`: Tiền tố đường dẫn có dấu gạch chéo ở cuối (ví dụ: `'fr/'`, `''`)
+  - `localePrefix`: Định danh locale không có dấu gạch chéo (ví dụ: `'fr'`, `undefined`)
+
+---
+
+## Ví dụ sử dụng
+
+### Sử dụng cơ bản
+
+```typescript codeFormat="typescript"
+import { getPrefix, Locales } from "intlayer";
+
+// Kiểm tra tiền tố cho locale tiếng Anh
+getPrefix(Locales.ENGLISH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// Trả về: { prefix: 'en/', localePrefix: 'en' }
+
+// Kiểm tra tiền tố cho locale tiếng Pháp
+getPrefix(Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Trả về: { prefix: 'fr/', localePrefix: 'fr' }
+```
+
+```javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// Trả về: { prefix: '', localePrefix: undefined }
+```
+
+```javascript codeFormat="commonjs"
+const { getPrefix, Locales } = require("intlayer");
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// Trả về: { prefix: '', localePrefix: undefined }
+```
+
+### Các chế độ định tuyến khác nhau
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// prefix-all: Luôn trả về tiền tố
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-all",
+  defaultLocale: Locales.ENGLISH,
+});
+// Trả về: { prefix: '/en', localePrefix: 'en' }
+
+// prefix-no-default: Không có tiền tố khi locale trùng với mặc định
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Trả về: { prefix: '', localePrefix: undefined }
+
+// prefix-no-default: Trả về tiền tố khi locale khác với mặc định
+getPrefix(Locales.FRENCH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Trả về: { prefix: 'fr/', localePrefix: 'fr' }
+
+// no-prefix & search-params: Không bao giờ trả về tiền tố
+getPrefix(Locales.ENGLISH, { mode: "no-prefix" });
+// Trả về: { prefix: '', localePrefix: undefined }
+
+getPrefix(Locales.ENGLISH, { mode: "search-params" });
+// Trả về: { prefix: '', localePrefix: undefined }
+```
+
+### Ví dụ Thực tế
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// Xây dựng URL với tiền tố phù hợp cho một locale cụ thể
+const locale = Locales.FRENCH;
+const { prefix, localePrefix } = getPrefix(locale, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+
+// Sử dụng prefix để xây dựng đường dẫn
+const url1 = `/${prefix}about`.replace(/\/+/g, "/");
+// Kết quả: "/fr/about"
+
+// Sử dụng localePrefix để nhận diện locale
+console.log(`Current locale: ${localePrefix}`);
+// Kết quả: "Current locale: fr"
+```
+
+---
+
+## Các Hàm Liên Quan
+
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getLocalizedUrl.md): Tạo URL có địa phương hóa cho một locale cụ thể
+- [`getMultilingualUrls`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getMultilingualUrls.md): Tạo các URL cho tất cả các locale đã cấu hình
+
+---
+
+## TypeScript
+
+```typescript
+type GetPrefixResult = {
+  prefix: string; // Tiền tố đường dẫn có dấu gạch chéo ở cuối (ví dụ: 'fr/' hoặc '')
+  localePrefix?: Locale; // Định danh locale không có dấu gạch chéo (ví dụ: 'fr' hoặc undefined)
+};
+
+function getPrefix(
+  locale: Locales,
+  options?: {
+    defaultLocale?: Locales;
+    mode?: "prefix-no-default" | "prefix-all" | "no-prefix" | "search-params";
+  }
+): GetPrefixResult;
+```

package/docs/zh/cli/build.md

@@ -0,0 +1,64 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 构建字典
+description: 了解如何从内容声明文件构建您的 Intlayer 字典。
+keywords:
+  - 构建
+  - 字典
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - build
+---
+
+# 构建字典
+
+要构建您的字典，您可以运行以下命令：
+
+```bash
+npx intlayer build
+```
+
+或者使用监听模式
+
+```bash
+npx intlayer build --watch
+```
+
+该命令默认会查找您的声明内容文件，路径为 `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}`。并在 `.intlayer` 目录中构建字典。
+
+## 别名：
+
+- `npx intlayer dictionaries build`
+- `npx intlayer dictionary build`
+- `npx intlayer dic build`
+
+## 参数：
+
+- **`--base-dir`**：指定项目的基础目录。为了获取 intlayer 配置，命令会在基础目录中查找 `intlayer.config.{ts,js,json,cjs,mjs}` 文件。
+
+  > 示例：`npx intlayer build --base-dir ./src`
+
+- **`--env`**：指定环境（例如，`development`、`production`）。当您在 intlayer 配置文件中使用环境变量时非常有用。
+
+  > 示例：`npx intlayer build --env production`
+
+- **`--env-file`**：提供自定义环境文件以加载变量。当您在 intlayer 配置文件中使用环境变量时非常有用。
+
+  > 示例：`npx intlayer build --env-file .env.production.local`
+
+- **`--with`**：与构建命令并行启动其他命令。
+
+  > 示例：`npx intlayer build --with "next dev --turbopack"`
+
+- **`--skip-prepare`**：跳过准备步骤。
+
+  > 示例：`npx intlayer build --skip-prepare`
+
+- **`--no-cache`**：禁用缓存。
+
+  > 示例：`npx intlayer build --no-cache`

package/docs/zh/cli/configuration.md

@@ -0,0 +1,63 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 管理配置
+description: 了解如何获取并推送您的 Intlayer 配置到 CMS。
+keywords:
+  - 配置
+  - Config
+  - CLI
+  - Intlayer
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - configuration
+---
+
+# 管理配置
+
+## 获取配置
+
+`configuration get` 命令用于检索当前 Intlayer 的配置，特别是语言环境设置。这对于验证您的设置非常有用。
+
+```bash
+npx intlayer configuration get
+```
+
+## 别名：
+
+- `npx intlayer config get`
+- `npx intlayer conf get`
+
+## 参数：
+
+- **`--env`**：指定环境（例如，`development`，`production`）。
+- **`--env-file`**：提供自定义环境文件以加载变量。
+- **`--base-dir`**：指定项目的基础目录。
+- **`--verbose`**：启用详细日志以进行调试。（默认通过 CLI 设置为 true）
+- **`--no-cache`**：禁用缓存。
+
+## 推送配置
+
+`configuration push` 命令将您的配置上传到 Intlayer CMS 和编辑器。此步骤对于启用 Intlayer 可视化编辑器中远程词典的使用是必要的。
+
+```bash
+npx intlayer configuration push
+```
+
+## 别名：
+
+- `npx intlayer config push`
+- `npx intlayer conf push`
+
+## 参数：
+
+- **`--env`**：指定环境（例如，`development`，`production`）。
+- **`--env-file`**：提供自定义环境文件以加载变量。
+- **`--base-dir`**：指定项目的基础目录。
+- **`--verbose`**：启用详细日志以便调试。（CLI 默认启用）
+- **`--no-cache`**：禁用缓存。
+
+通过推送配置，您的项目将完全集成到 Intlayer CMS 中，实现团队间无缝的词典管理。

package/docs/zh/cli/debug.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 调试 Intlayer 命令
+description: 学习如何调试和排查 Intlayer CLI 问题。
+keywords:
+  - 调试
+  - 排查
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - debug
+---
+
+# 调试 intlayer 命令
+
+## 1. **确保你使用的是最新版本**
+
+运行：
+
+```bash
+npx intlayer --version                  # 当前本地 intlayer 版本
+npx intlayer@latest --version           # 当前最新 intlayer 版本
+```
+
+## 2. **检查命令是否已注册**
+
+你可以使用以下命令检查：
+
+```bash
+npx intlayer --help                     # 显示可用命令列表和使用信息
+npx intlayer dictionary build --help    # 显示某个命令的可用选项列表
+```
+
+## 3. **重启你的终端**
+
+有时需要重启终端才能识别新命令。
+
+## 4. **清除 npx 缓存（如果你卡在旧版本）**
+
+```bash
+npx clear-npx-cache
+```

package/docs/zh/cli/doc-review.md

@@ -0,0 +1,43 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 审核文档
+description: 学习如何审核不同语言版本的文档文件，以确保质量、一致性和完整性。
+keywords:
+  - 审核
+  - 文档
+  - 文档管理
+  - AI
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - doc-review
+---
+
+# 审核文档
+
+`doc review` 命令用于分析不同语言版本的文档文件，检查其质量、一致性和完整性。
+
+```bash
+npx intlayer doc review
+```
+
+该命令可用于审核已翻译的文件，并检查翻译是否正确。
+
+在大多数使用场景中，
+
+- 当该文件的翻译版本不可用时，优先使用 `doc translate`。
+- 当该文件的翻译版本已存在时，优先使用 `doc review`。
+
+> 请注意，审核过程比翻译过程消耗更多的输入令牌来完整审核同一文件。然而，审核过程会优化需要审核的块，并跳过未更改的部分。
+
+## 参数：
+
+`doc review` 命令接受与 `doc translate` 相同的参数，允许您审核特定的文档文件并应用质量检查。
+
+如果您启用了其中一个 git 选项，命令将只审核文件中发生更改的部分。脚本会将文件分块处理并审核每个块。如果某个块没有更改，脚本将跳过该块，以加快审核过程并限制 AI 提供商 API 的成本。
+
+有关完整的参数列表，请参阅[翻译文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/doc-translate.md)命令文档。