@intlayer/docs 7.5.10 → 7.5.12

package/docs/vi/plugins/sync-json.md

@@ -108,18 +108,22 @@ syncJSON({
   source: ({ key, locale }) => string, // bắt buộc
   location?: string, // nhãn tùy chọn, mặc định: "plugin"
   priority?: number, // ưu tiên tùy chọn để giải quyết xung đột, mặc định: 0
-  format?: 'intlayer' | 'icu' | 'i18next', // bộ định dạng tùy chọn, mặc định: 'intlayer'
+  format?: 'intlayer' | 'icu' | 'i18next', // bộ định dạng tùy chọn, được sử dụng cho tương thích runtime Intlayer
 });
 ```
 
 #### `format` ('intlayer' | 'icu' | 'i18next')
 
-Chỉ định bộ định dạng sẽ được sử dụng cho nội dung từ điển khi đồng bộ hóa các tệp JSON. Điều này cho phép sử dụng các cú pháp định dạng thông báo khác nhau tương thích với các thư viện i18n khác nhau.
+Chỉ định bộ định dạng sẽ được sử dụng cho nội dung từ điển khi đồng bộ hóa các tệp JSON. Điều này cho phép sử dụng các cú pháp định dạng thông báo khác nhau tương thích với runtime Intlayer.
 
+- `undefined`: Không sử dụng bộ định dạng nào, nội dung JSON sẽ được sử dụng nguyên trạng.
 - `'intlayer'`: Bộ định dạng Intlayer mặc định (mặc định).
 - `'icu'`: Sử dụng định dạng thông báo ICU (tương thích với các thư viện như react-intl, vue-i18n).
 - `'i18next'`: Sử dụng định dạng thông báo i18next (tương thích với i18next, next-i18next, Solid-i18next).
 
+> Lưu ý rằng việc sử dụng bộ định dạng sẽ chuyển đổi nội dung JSON của bạn ở đầu vào và đầu ra. Đối với các quy tắc JSON phức tạp như số nhiều ICU, việc phân tích có thể không đảm bảo ánh xạ 1 đối 1 giữa đầu vào và đầu ra.
+> Nếu bạn không sử dụng runtime Intlayer, bạn có thể muốn không thiết lập bộ định dạng.
+
 **Ví dụ:**
 
 ```ts

package/docs/zh/cli/ci.md

@@ -0,0 +1,137 @@
+---
+createdAt: 2026-01-06
+updatedAt: 2026-01-06
+title: CI 命令
+description: 了解如何在 CI/CD 管道和 monorepo 中使用自动注入的凭据运行 Intlayer 命令。
+keywords:
+  - CI
+  - CI/CD
+  - 自动化
+  - Monorepo
+  - 凭据
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - ci
+history:
+  - version: 7.5.11
+    date: 2026-01-06
+    changes: 添加 CI 命令
+---
+
+# CI 命令
+
+```bash
+npx intlayer ci <command...>
+```
+
+CI 命令专为自动化和 CI/CD 管道而设计。它会自动从 `INTLAYER_PROJECT_CREDENTIALS` 环境变量注入凭据，并可以在 monorepo 中的多个项目上运行 Intlayer 命令。
+
+## 工作原理
+
+CI 命令以两种模式运行：
+
+1. **单项目模式**：如果当前工作目录与 `INTLAYER_PROJECT_CREDENTIALS` 中的项目路径之一匹配，则仅针对该特定项目运行命令。
+
+2. **迭代模式**：如果未检测到特定的项目上下文，它会遍历所有已配置的项目并为每个项目运行命令。
+
+## 环境变量
+
+该命令需要设置 `INTLAYER_PROJECT_CREDENTIALS` 环境变量。此变量应包含一个 JSON 对象，将项目路径映射到其凭据：
+
+```json
+{
+  "packages/app": {
+    "clientId": "your-client-id-1",
+    "clientSecret": "your-client-secret-1"
+  },
+  "packages/admin": {
+    "clientId": "your-client-id-2",
+    "clientSecret": "your-client-secret-2"
+  }
+}
+```
+
+## 包管理器检测
+
+CI 命令会根据 `npm_config_user_agent` 环境变量自动检测正在使用的包管理器（npm、yarn、pnpm 或 bun），并使用适当的命令来执行 Intlayer。
+
+## 参数
+
+- **`<command...>`**：要执行的 Intlayer 命令（例如，`fill`、`push`、`build`）。您可以传递任何 Intlayer 命令及其参数。
+
+  > 示例: `npx intlayer ci fill --verbose`
+  >
+  > 示例: `npx intlayer ci push`
+  >
+  > 示例: `npx intlayer ci build`
+
+## 示例
+
+### 在单项目模式下运行命令
+
+如果您在匹配 `INTLAYER_PROJECT_CREDENTIALS` 中路径之一的项目目录中：
+
+```bash
+cd packages/app
+npx intlayer ci fill
+```
+
+这将为 `packages/app` 项目自动注入凭据并运行 `fill` 命令。
+
+### 在所有项目上运行命令
+
+如果您在未匹配任何项目路径的目录中，该命令将遍历所有已配置的项目：
+
+```bash
+cd /path/to/monorepo
+npx intlayer ci push
+```
+
+这将为 `INTLAYER_PROJECT_CREDENTIALS` 中配置的每个项目运行 `push` 命令。
+
+### 传递额外标志
+
+您可以将任何标志传递给底层 Intlayer 命令：
+
+```bash
+npx intlayer ci fill --verbose --mode complete
+```
+
+### 在 CI/CD 管道中使用
+
+在您的 CI/CD 配置中（例如，GitHub Actions、GitLab CI），将 `INTLAYER_PROJECT_CREDENTIALS` 设置为密钥：
+
+```yaml
+# GitHub Actions 示例
+env:
+  INTLAYER_PROJECT_CREDENTIALS: ${{ secrets.INTLAYER_PROJECT_CREDENTIALS }}
+
+steps:
+  - name: 填充字典
+    run: npx intlayer ci fill
+```
+
+## 错误处理
+
+- 如果未设置 `INTLAYER_PROJECT_CREDENTIALS`，命令将以错误退出。
+- 如果 `INTLAYER_PROJECT_CREDENTIALS` 不是有效的 JSON，命令将以错误退出。
+- 如果项目路径不存在，将跳过并显示警告。
+- 如果任何项目失败，命令将以非零状态代码退出。
+
+## 使用场景
+
+- **Monorepo 自动化**：在 monorepo 中的多个项目上运行 Intlayer 命令
+- **CI/CD 管道**：在持续集成工作流中自动化字典管理
+- **批量操作**：同时对多个 Intlayer 项目执行相同操作
+- **密钥管理**：使用环境变量安全地管理多个项目的凭据
+
+## 安全最佳实践
+
+- 在 CI/CD 平台中将 `INTLAYER_PROJECT_CREDENTIALS` 存储为加密密钥
+- 永远不要将凭据提交到版本控制
+- 为不同的部署环境使用特定于环境的凭据
+- 定期轮换凭据

package/docs/zh/cli/index.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-12-30
+updatedAt: 2026-01-06
 title: CLI
 description: 了解如何使用 Intlayer CLI 来管理您的多语言网站。按照本在线文档中的步骤，几分钟内即可设置您的项目。
 keywords:
@@ -17,6 +17,9 @@ slugs:
   - concept
   - cli
 history:
+  - version: 7.5.11
+    date: 2026-01-06
+    changes: 添加 projects list 命令
   - version: 7.5.9
     date: 2025-12-30
     changes: 添加 init 命令
@@ -119,6 +122,7 @@ Intlayer 支持多种配置文件格式：
 - **[构建字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/build.md)** - 从内容声明文件构建字典
 - **[监视字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/watch.md)** - 监视更改并自动构建字典
 - **[检查 CLI 版本](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/version.md)** - 检查已安装的 Intlayer CLI 版本
+- **[列出项目](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/list_projects.md)** - 列出目录或 git 存储库中的所有 Intlayer 项目
 
 ### 字典管理
 
@@ -171,6 +175,7 @@ Intlayer 支持多种配置文件格式：
   "intlayer:list": "npx intlayer content list",
   "intlayer:test": "npx intlayer content test",
   "intlayer:transform": "npx intlayer transform",
+  "intlayer:projects": "npx intlayer projects list",
   "intlayer:doc:translate": "npx intlayer doc translate",
   "intlayer:doc:review": "npx intlayer doc review"
 }
@@ -180,3 +185,4 @@ Intlayer 支持多种配置文件格式：
 >
 > - 使用 `npx intlayer list` 替代 `npx intlayer content list`
 > - 使用 `npx intlayer test` 替代 `npx intlayer content test`
+> - 使用 `npx intlayer projects-list` 或 `npx intlayer pl` 替代 `npx intlayer projects list`

package/docs/zh/cli/list.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-01-06
 title: 列出内容声明文件
 description: 了解如何列出项目中的所有内容声明文件。
 keywords:
@@ -13,6 +13,13 @@ slugs:
   - concept
   - cli
   - list
+history:
+  - version: 7.5.12
+    date: 2026-01-06
+    changes: 为 list 命令添加绝对路径输出选项
+  - version: 7.5.11
+    date: 2026-01-06
+    changes: 为 list 命令添加 JSON 输出选项
 ---
 
 # 列出内容声明文件
@@ -27,14 +34,36 @@ npx intlayer content list
 
 此命令显示项目中所有内容声明文件，展示它们的字典键和文件路径。它有助于概览所有内容文件，并验证它们是否被 Intlayer 正确发现。
 
+## 参数：
+
+- **`--json`**: 以 JSON 格式输出结果，而不是格式化文本。对脚本编写和程序化访问很有用。
+
+  > 示例: `npx intlayer content list --json`
+
 ## 示例：
 
+### 列出内容声明文件：
+
 ```bash
 npx intlayer content list
 ```
 
+### 以 JSON 格式输出：
+
+```bash
+npx intlayer content list --json
+```
+
+### 以绝对路径输出：
+
+```bash
+npx intlayer content list --absolute
+```
+
 ## 示例输出：
 
+### 格式化输出：
+
 ```bash
 npx intlayer content list
 Content declaration files:
@@ -45,6 +74,14 @@ Content declaration files:
 内容声明文件总数：3
 ```
 
+### JSON 输出：
+
+```bash
+$ npx intlayer content list --json
+
+[{"key":"home-page","path":"src/components/HomePage/homePage.content.ts"},{"key":"server-component","path":"src/components/ServerComponent/serverComponent.content.ts"},{"key":"client-component","path":"src/components/ClientComponent/clientComponent.content.ts"}]
+```
+
 此命令将输出：
 
 - 所有内容声明文件的格式化列表，包含它们的键和相对文件路径

package/docs/zh/cli/list_projects.md

@@ -0,0 +1,130 @@
+---
+createdAt: 2025-12-30
+updatedAt: 2026-01-06
+title: 列出 Intlayer 项目
+description: 了解如何在目录或 git 仓库中列出所有 Intlayer 项目。
+keywords:
+  - List
+  - Projects
+  - CLI
+  - Intlayer
+  - Git
+slugs:
+  - doc
+  - concept
+  - cli
+  - list-projects
+history:
+  - version: 7.5.12
+    date: 2026-01-06
+    changes: 向 list projects 命令添加绝对路径输出选项
+---
+
+# 列出 Intlayer 项目
+
+```bash
+npx intlayer projects list
+```
+
+此命令通过查找包含 Intlayer 配置文件的目录来搜索并列出所有 Intlayer 项目。对于在 monorepo、workspace 或 git 仓库中发现所有 Intlayer 项目非常有用。
+
+## 别名：
+
+- `npx intlayer projects-list`
+- `npx intlayer pl`
+
+## 参数：
+
+- **`--base-dir [path]`**：指定要从其开始搜索的基目录。默认是当前工作目录。
+
+  > 示例：`npx intlayer projects list --base-dir /path/to/workspace`
+
+  > 示例：`npx intlayer projects list --base-dir /path/to/workspace`
+
+- **`--git-root`**：从 git 根目录开始搜索，而不是基目录。这对于在 monorepo 或 git 仓库中查找所有 Intlayer 项目很有用。
+
+  > 示例：`npx intlayer projects list --git-root`
+
+- **`--json`**：以 JSON 格式输出结果，而不是格式化文本。对脚本编写和程序化访问很有用。
+
+  > 示例：`npx intlayer projects list --json`
+
+- **`--absolute`**：以绝对路径输出结果，而不是相对路径。
+
+  > 示例：`npx intlayer projects list --absolute`
+
+## 工作原理：
+
+该命令将在指定目录（如果使用了 `--git-root` 则在 git 根目录）中搜索 Intlayer 配置文件。它会查找以下配置文件模式：
+
+- `intlayer.config.ts`
+- `intlayer.config.js`
+- `intlayer.config.json`
+- `intlayer.config.cjs`
+- `intlayer.config.mjs`
+- `.intlayerrc`
+
+每个包含上述任一文件的目录都被视为一个 Intlayer 项目，并将在输出中列出。
+
+## 示例：
+
+### 列出当前目录中的项目：
+
+```bash
+npx intlayer projects list
+```
+
+### 在特定目录中列出项目：
+
+```bash
+npx intlayer projects list --base-dir ./packages
+```
+
+### 列出 git 仓库中的所有项目：
+
+```bash
+npx intlayer projects list --git-root
+```
+
+### 使用快捷别名：
+
+```bash
+npx intlayer pl --git-root
+```
+
+### 以 JSON 格式输出：
+
+```bash
+npx intlayer projects list --json
+```
+
+## 示例输出：
+
+### 格式化输出：
+
+```bash
+$ npx intlayer projects list --git-root
+
+Found 3 Intlayer project(s):
+
+  - /Users/user/workspace/packages/app
+  - /Users/user/workspace/packages/admin
+  - /Users/user/workspace/packages/shared
+```
+
+### JSON 输出：
+
+```bash
+$ npx intlayer projects list --json
+
+["/Users/user/workspace/packages/app","/Users/user/workspace/packages/admin","/Users/user/workspace/packages/shared"]
+```
+
+## 使用场景：
+
+- **Monorepo 管理**：在 monorepo 结构中发现所有 Intlayer 项目
+- **项目发现**：在工作区中查找所有启用 Intlayer 的项目
+- **CI/CD**：在自动化工作流中验证 Intlayer 项目
+- **文档**：生成列出所有使用 Intlayer 的项目的文档
+
+输出提供每个项目目录的绝对路径，便于导航或对多个 Intlayer 项目进行脚本化操作。

package/docs/zh/intlayer_CMS.md

@@ -71,6 +71,26 @@ Intlayer 区分“本地”字典和“远程”字典。
 
 ## 配置
 
+运行以下命令登录 Intlayer CMS：
+
+```bash packageManager="npm"
+npx intlayer login
+```
+
+```bash packageManager="yarn"
+yarn intlayer login
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer login
+```
+
+```bash packageManager="bun"
+bunx intlayer login
+```
+
+这将打开您的默认浏览器以完成身份验证过程并接收使用 Intlayer 服务所需的凭据（客户端 ID 和客户端密钥）。
+
 在您的 Intlayer 配置文件中，您可以自定义 CMS 设置：
 
 ```typescript fileName="intlayer.config.ts" codeFormat="typescript"

package/docs/zh/intlayer_with_next-i18next.md

@@ -593,7 +593,6 @@ const config: IntlayerConfig = {
   },
   plugins: [
     syncJSON({
-      format: "i18next",
       source: ({ locale }) => `./locales/${locale}.json`,
     }),
   ],

package/docs/zh/intlayer_with_nextjs_14.md

@@ -81,6 +81,34 @@ bunx intlayer init
 
 ### 第 2 步：配置您的项目
 
+Here is the final structure that we will make:
+
+```bash
+.
+├── src
+│   ├── app
+│   │   ├── [locale]
+│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider
+│   │   │   ├── page.content.ts
+│   │   │   └── page.tsx
+│   │   └── layout.tsx                # Root layout for style and global providers
+│   ├── components
+│   │   ├── client-component-example.content.ts
+│   │   ├── ClientComponentExample.tsx
+│   │   ├── LocaleSwitcher
+│   │   │   ├── localeSwitcher.content.ts
+│   │   │   └── LocaleSwitcher.tsx
+│   │   ├── server-component-example.content.ts
+│   │   └── ServerComponentExample.tsx
+│   └── middleware.ts
+├── intlayer.config.ts
+├── next.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+> If you don't want locale routing, intlayer can be used as a simple provider / hook. See [this guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_no_locale_path.md) for more details.
+
 创建一个配置文件来配置您应用的语言：
 
 ```typescript fileName="intlayer.config.ts" codeFormat="typescript"

package/docs/zh/intlayer_with_nextjs_15.md

@@ -84,6 +84,34 @@ bunx intlayer init
 
 ### 第 2 步：配置您的项目
 
+Here is the final structure that we will make:
+
+```bash
+.
+├── src
+│   ├── app
+│   │   ├── [locale]
+│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider
+│   │   │   ├── page.content.ts
+│   │   │   └── page.tsx
+│   │   └── layout.tsx                # Root layout for style and global providers
+│   ├── components
+│   │   ├── client-component-example.content.ts
+│   │   ├── ClientComponentExample.tsx
+│   │   ├── LocaleSwitcher
+│   │   │   ├── localeSwitcher.content.ts
+│   │   │   └── LocaleSwitcher.tsx
+│   │   ├── server-component-example.content.ts
+│   │   └── ServerComponentExample.tsx
+│   └── middleware.ts
+├── intlayer.config.ts
+├── next.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+> If you don't want locale routing, intlayer can be used as a simple provider / hook. See [this guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_no_locale_path.md) for more details.
+
 创建一个配置文件以配置您应用程序的语言：
 
 ```typescript fileName="intlayer.config.ts" codeFormat="typescript"

package/docs/zh/intlayer_with_nextjs_16.md

@@ -104,6 +104,34 @@ bunx intlayer init
 
 ### 第 2 步：配置您的项目
 
+Here is the final structure that we will make:
+
+```bash
+.
+├── src
+│   ├── app
+│   │   ├── [locale]
+│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider
+│   │   │   ├── page.content.ts
+│   │   │   └── page.tsx
+│   │   └── layout.tsx                # Root layout for style and global providers
+│   ├── components
+│   │   ├── client-component-example.content.ts
+│   │   ├── ClientComponentExample.tsx
+│   │   ├── LocaleSwitcher
+│   │   │   ├── localeSwitcher.content.ts
+│   │   │   └── LocaleSwitcher.tsx
+│   │   ├── server-component-example.content.ts
+│   │   └── ServerComponentExample.tsx
+│   └── proxy.ts
+├── intlayer.config.ts
+├── next.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+> If you don't want locale routing, intlayer can be used as a simple provider / hook. See [this guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_no_locale_path.md) for more details.
+
 创建一个配置文件来配置您的应用程序语言：
 
 ```typescript fileName="intlayer.config.ts" codeFormat="typescript"