@intlayer/docs 5.5.8

package/zh/intlayer_cli.md

@@ -0,0 +1,274 @@
+# Intlayer CLI
+
+## 安装包
+
+使用 npm 安装必要的包：
+
+```bash packageManager="npm"
+npm install intlayer-cli -g
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-cli -g
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-cli -g
+```
+
+> 如果已经安装了 `intlayer` 包，CLI 会自动安装。您可以跳过此步骤。
+
+## intlayer-cli 包
+
+`intlayer-cli` 包旨在将您的 [intlayer 声明](https://github.com/aymericzip/intlayer/blob/main/docs/zh/dictionary/get_started.md) 转换为字典。
+
+此包将转换所有的 intlayer 文件，例如 `src/**/*.content.{ts|js|mjs|cjs|json}`。[查看如何声明您的 Intlayer 声明文件](https://github.com/aymericzip/intlayer/blob/main/packages/intlayer/README.md)。
+
+要解释 intlayer 字典，您可以使用解释器，例如 [react-intlayer](https://www.npmjs.com/package/react-intlayer) 或 [next-intlayer](https://www.npmjs.com/package/next-intlayer)。
+
+## 配置文件支持
+
+Intlayer 支持多种配置文件格式：
+
+- `intlayer.config.ts`
+- `intlayer.config.js`
+- `intlayer.config.json`
+- `intlayer.config.cjs`
+- `intlayer.config.mjs`
+- `.intlayerrc`
+
+要了解如何配置可用的语言环境或其他参数，请参考[此处的配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)。
+
+## 运行 intlayer 命令
+
+### 构建字典
+
+要构建您的字典，可以运行以下命令：
+
+```bash
+npx intlayer dictionaries build
+```
+
+或者使用监视模式
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+此命令将默认查找您的声明内容文件，例如 `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}`，并在 `.intlayer` 目录中构建字典。
+
+### 推送字典
+
+```bash
+npx intlayer dictionary push
+```
+
+如果安装了 [intlayer 编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_visual_editor.md)，您还可以将字典推送到编辑器。此命令将使字典可用于[编辑器](https://intlayer.org/dashboard)。通过这种方式，您可以与团队共享字典并编辑内容，而无需编辑应用程序代码。
+
+##### 参数：
+
+- `-d`, `--dictionaries`: 要推送的字典ID。如果未指定，将推送所有字典。
+  > 示例：`npx intlayer dictionary push -d my-dictionary-id my-other-dictionary-id`
+- `-r`, `--deleteLocaleDictionary`: 跳过询问是否在推送字典后删除语言目录，并删除。默认情况下，如果字典在本地定义，它将覆盖远程字典的内容。
+  > 示例：`npx intlayer dictionary push -r`
+- `-k`, `--keepLocaleDictionary`: 跳过询问是否在推送字典后删除语言目录，并保留。默认情况下，如果字典在本地定义，它将覆盖远程字典的内容。
+  > 示例：`npx intlayer dictionary push -k`
+- `--env`: 指定环境（例如：`development`、`production`）。
+- `--env-file`: 提供自定义环境文件以加载变量。
+- `--base-dir`: 指定项目的基本目录。
+- `--verbose`: 启用详细日志记录以进行调试。
+- `--git-diff`: 仅执行在git仓库中有未推送更改的字典。
+- `--git-diff-base`: 指定git diff的基本引用。
+- `--git-diff-current`: 指定git diff的当前引用。
+- `--uncommitted`: 包含未提交的更改。
+- `--unpushed`: 包含未推送的更改。
+- `--untracked`: 包含未跟踪的文件。
+
+### 拉取远程字典
+
+```bash
+npx intlayer dictionary pull
+```
+
+如果安装了 [intlayer 编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_visual_editor.md)，您还可以从编辑器拉取字典。通过这种方式，您可以根据应用程序的需要覆盖字典的内容。
+
+##### 参数：
+
+- `-d, --dictionaries`: 要拉取的字典ID。如果未指定，将拉取所有字典。
+  > 示例：`npx intlayer dictionary pull -d my-dictionary-id my-other-dictionary-id`
+- `--newDictionariesPath`: 新字典将存储的目录路径。如果未指定，新字典将存储在项目的`./intlayer-dictionaries`目录中。如果字典内容中指定了`filePath`字段，字典将存储在指定的`filePath`目录中，忽略此参数。
+- `--env`: 指定环境（例如：`development`、`production`）。
+- `--env-file`: 提供自定义环境文件以加载变量。
+- `--base-dir`: 指定项目的基本目录。
+- `--verbose`: 启用详细日志记录以进行调试。
+
+##### 示例：
+
+```bash
+npx intlayer dictionary pull --newDictionariesPath ./my-dictionaries-dir/
+```
+
+### 审核字典
+
+```bash
+npx intlayer audit
+```
+
+此命令分析您的内容声明文件中的潜在问题，例如缺失的翻译、结构不一致或类型不匹配。如果发现任何问题，**intlayer audit** 将提出或应用更新，以保持字典的一致性和完整性。
+
+##### 参数：
+
+- **`-f, --files [files...]`**  
+  要审核的特定内容声明文件列表。如果未提供，将审核所有发现的 `*.content.{ts,js,mjs,cjs,tsx,jsx,json}` 文件。
+
+- **`--exclude [excludedGlobs...]`**  
+  要从审核中排除的全局模式（例如 `--exclude "src/test/**"`）。
+
+- **`--source-locale [sourceLocale]`**  
+  要翻译的源语言。如果未指定，将使用配置中的默认语言。
+
+- **`--output-locales [outputLocales...]`**  
+  要翻译的目标语言。如果未指定，将使用配置中除源语言外的所有语言。
+
+- **`--mode [mode]`**  
+  翻译模式：'complete'、'review'或'missing-only'。默认为'missing-only'。
+
+- **`--git-diff`**  
+  仅执行在git仓库中有未推送更改的字典。
+
+- **`--git-diff-base`**  
+  指定git diff的基本引用。
+
+- **`--git-diff-current`**  
+  指定git diff的当前引用。
+
+- **`--uncommitted`**  
+  包含未提交的更改。
+
+- **`--unpushed`**  
+  包含未推送的更改。
+
+- **`--untracked`**  
+  包含未跟踪的文件。
+
+- **`--keys [keys...]`**  
+  基于指定键过滤字典。
+
+- **`--excluded-keys [excludedKeys...]`**  
+  基于指定键排除字典。
+
+- **`--path-filter [pathFilters...]`**  
+  基于文件路径的glob模式过滤字典。
+
+- **`--model [model]`**  
+  用于翻译的AI模型（例如：`gpt-3.5-turbo`）。
+
+- **`--provider [provider]`**  
+  用于翻译的AI提供商。
+
+- **`--temperature [temperature]`**  
+  AI模型的温度设置。
+
+- **`--api-key [apiKey]`**  
+  为AI服务提供您自己的API密钥。
+
+- **`--custom-prompt [prompt]`**  
+  为翻译指令提供自定义提示。
+
+- **`--application-context [applicationContext]`**  
+  为AI翻译提供额外的上下文。
+
+- **`--env`**  
+  指定环境（例如：`development`、`production`）。
+
+- **`--env-file [envFile]`**  
+  提供自定义环境文件以加载变量。
+
+- **`--base-dir`**  
+  指定项目的基本目录。
+
+- **`--verbose`**  
+  启用详细日志记录以进行调试。
+
+##### 示例：
+
+```bash
+npx intlayer audit --exclude "tests/**" --model gpt-3.5-turbo
+```
+
+此命令将忽略 `tests/**` 下的任何文件，并使用 `gpt-3.5-turbo` 模型审核发现的内容声明文件。如果发现任何问题（例如缺失的翻译），它们将被就地修正，同时保留原始文件结构。
+
+### 管理配置
+
+#### 获取配置
+
+`get configuration` 命令检索 Intlayer 的当前配置，特别是语言环境设置。这对于验证您的设置非常有用。
+
+```bash
+npx intlayer config get
+```
+
+##### 参数：
+
+- **`--env`**: 指定环境（例如 `development`，`production`）。
+- **`--env-file`**: 提供自定义环境文件以加载变量。
+- **`--base-dir`**: 指定项目的基本目录。
+- **`--verbose`**: 启用详细日志记录以进行调试。
+
+#### 推送配置
+
+`push configuration` 命令将您的配置上传到 Intlayer CMS 和编辑器。此步骤对于在 Intlayer 可视化编辑器中启用远程字典的使用是必要的。
+
+```bash
+npx intlayer config push
+```
+
+##### 参数：
+
+- **`--env`**: 指定环境（例如 `development`，`production`）。
+- **`--env-file`**: 提供自定义环境文件以加载变量。
+- **`--base-dir`**: 指定项目的基本目录。
+- **`--verbose`**: 启用详细日志记录以进行调试。
+
+通过推送配置，您的项目将完全集成到 Intlayer CMS 中，从而实现团队间的无缝字典管理。
+
+## 在 `package.json` 中使用 intlayer 命令
+
+```json fileName="package.json"
+"scripts": {
+  "intlayer:build": "npx intlayer dictionaries build",
+  "intlayer:watch": "npx intlayer dictionaries build --watch",
+  "intlayer:push": "npx intlayer dictionary push",
+  "intlayer:pull": "npx intlayer dictionary pull",
+  "intlayer:audit": "npx intlayer audit"
+}
+```
+
+## 调试 intlayer 命令
+
+### 1. **确保使用最新版本**
+
+运行:
+
+```bash
+npx intlayer --version                  # 当前本地 intlayer 版本
+npx intlayer@latest --version          # 最新 intlayer 版本
+```
+
+### 2. **检查命令是否已注册**
+
+您可以通过以下方式检查:
+
+```bash
+npx intlayer --help      # 显示可用命令列表和使用信息
+```
+
+### 3. **重启终端**
+
+有时需要重启终端才能识别新命令。
+
+### 4. **清除 npx 缓存（如果卡在旧版本）**
+
+```bash
+npx clear-npx-cache
+```

package/zh/intlayer_visual_editor.md

@@ -0,0 +1,210 @@
+# Intlayer 可视化编辑器文档
+
+<iframe title="Visual Editor + CMS for Your Web App: Intlayer Explained" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/UDDTnirwi_4?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+Intlayer 可视化编辑器是一种工具，可以将您的网站包装起来，通过可视化编辑器与您的内容声明文件进行交互。
+
+![Intlayer 可视化编辑器界面](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.gif)
+
+`intlayer-editor` 包基于 Intlayer，可用于 JavaScript 应用程序，例如 React (Create React App)、Vite + React 和 Next.js。
+
+## 可视化编辑器 vs CMS
+
+Intlayer 可视化编辑器是一种工具，允许您在本地字典的可视化编辑器中管理内容。一旦进行了更改，内容将在代码库中被替换。这意味着应用程序将被重新构建，页面将重新加载以显示新内容。
+
+相比之下，[Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_CMS.md) 是一种工具，允许您在远程字典的可视化编辑器中管理内容。一旦进行了更改，内容将**不会**影响您的代码库。网站将自动显示更改后的内容。
+
+## 将 Intlayer 集成到您的应用程序中
+
+有关如何集成 Intlayer 的更多详细信息，请参阅以下相关部分：
+
+### 与 Next.js 集成
+
+有关与 Next.js 集成的内容，请参阅[设置指南](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_nextjs_15.md)。
+
+### 与 Create React App 集成
+
+有关与 Create React App 集成的内容，请参阅[设置指南](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_create_react_app.md)。
+
+### 与 Vite + React 集成
+
+有关与 Vite + React 集成的内容，请参阅[设置指南](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_vite+react.md)。
+
+## Intlayer 编辑器如何工作
+
+应用程序中的可视化编辑器包括以下两部分：
+
+- 一个前端应用程序，它将在 iframe 中显示您的网站。如果您的网站使用了 Intlayer，可视化编辑器将自动检测您的内容，并允许您与之交互。一旦进行了修改，您将能够下载更改。
+
+- 当您点击下载按钮时，可视化编辑器将向服务器发送请求，用新内容替换您的内容声明文件（无论这些文件在您的项目中声明在哪里）。
+
+> 请注意，目前 Intlayer 编辑器将您的内容声明文件写为 JSON 文件。
+
+## 安装
+
+在您的项目中配置好 Intlayer 后，只需将 `intlayer-editor` 安装为开发依赖项：
+
+```bash packageManager="npm"
+npm install intlayer-editor --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-editor --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-editor --save-dev
+```
+
+## 配置
+
+在您的 Intlayer 配置文件中，您可以自定义编辑器设置：
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... 其他配置设置
+  editor: {
+    /**
+     * 必需
+     * 应用程序的 URL。
+     * 这是可视化编辑器的目标 URL。
+     * 示例：'http://localhost:3000'
+     */
+    applicationURL: process.env.INTLAYER_APPLICATION_URL,
+    /**
+     * 可选
+     * 默认值为 `true`。如果为 `false`，编辑器将处于非活动状态且无法访问。
+     * 可用于出于安全原因在特定环境（如生产环境）中禁用编辑器。
+     */
+    enabled: process.env.INTLAYER_ENABLED,
+    /**
+     * 可选
+     * 默认值为 `8000`。
+     * 编辑器服务器的端口。
+     */
+    port: process.env.INTLAYER_PORT,
+    /**
+     * 可选
+     * 默认值为 "http://localhost:8000"
+     * 编辑器服务器的 URL。
+     */
+    editorURL: process.env.INTLAYER_EDITOR_URL,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... 其他配置设置
+  editor: {
+    /**
+     * 必需
+     * 应用程序的 URL。
+     * 这是可视化编辑器的目标 URL。
+     * 示例：'http://localhost:3000'
+     */
+    applicationURL: process.env.INTLAYER_APPLICATION_URL,
+    /**
+     * 可选
+     * 默认值为 `true`。如果为 `false`，编辑器将处于非活动状态且无法访问。
+     * 可用于出于安全原因在特定环境（如生产环境）中禁用编辑器。
+     */
+    enabled: process.env.INTLAYER_ENABLED,
+    /**
+     * 可选
+     * 默认值为 `8000`。
+     * 可视化编辑器服务器使用的端口。
+     */
+    port: process.env.INTLAYER_PORT,
+    /**
+     * 可选
+     * 默认值为 "http://localhost:8000"
+     * 应用程序可访问的编辑器服务器 URL。用于限制可以与应用程序交互的来源以提高安全性。如果设置为 `'*'`，编辑器可以从任何来源访问。如果更改了端口，或者编辑器托管在不同的域上，则应设置此项。
+     */
+    editorURL: process.env.INTLAYER_EDITOR_URL,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... 其他配置设置
+  editor: {
+    /**
+     * 必需
+     * 应用程序的 URL。
+     * 这是可视化编辑器的目标 URL。
+     */
+    applicationURL: process.env.INTLAYER_APPLICATION_URL,
+    /**
+     * 可选
+     * 默认值为 `8000`。
+     * 编辑器服务器的端口。
+     */
+    port: process.env.INTLAYER_PORT,
+    /**
+     * 可选
+     * 默认值为 "http://localhost:8000"
+     * 编辑器服务器的 URL。
+     */
+    editorURL: process.env.INTLAYER_EDITOR_URL,
+    /**
+     * 可选
+     * 默认值为 `true`。如果为 `false`，编辑器将处于非活动状态且无法访问。
+     * 可用于出于安全原因在特定环境（如生产环境）中禁用编辑器。
+     */
+    enabled: process.env.INTLAYER_ENABLED,
+  },
+};
+
+module.exports = config;
+```
+
+> 要查看所有可用参数，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)。
+
+## 使用编辑器
+
+1. 安装编辑器后，您可以使用以下命令启动编辑器：
+
+   ```bash packageManager="npm"
+   npx intlayer-editor start
+   ```
+
+   ```bash packageManager="yarn"
+   yarn intlayer-editor start
+   ```
+
+   ```bash packageManager="pnpm"
+   pnpm intlayer-editor start
+   ```
+
+   > **请注意，您应该并行运行您的应用程序。** 应用程序 URL 应与您在编辑器配置中设置的 URL (`applicationURL`) 匹配。
+
+2. 然后，打开提供的 URL。默认值为 `http://localhost:8000`。
+
+   您可以通过将光标悬停在内容上查看每个由 Intlayer 索引的字段。
+
+   ![悬停在内容上](https://github.com/aymericzip/intlayer/blob/main/docs/assets/intlayer_editor_hover_content.png)
+
+3. 如果您的内容被标出，您可以长按它以显示编辑抽屉。
+
+## 调试
+
+如果您在使用可视化编辑器时遇到任何问题，请检查以下内容：
+
+- 可视化编辑器和应用程序是否正在运行。
+
+- [`editor`](https://intlayer.org/doc/concept/configuration#editor-configuration) 配置是否正确设置在您的 Intlayer 配置文件中。
+
+  - 必需字段：
+    - 应用程序 URL 应与您在编辑器配置中设置的 URL (`applicationURL`) 匹配。
+
+- 可视化编辑器使用 iframe 显示您的网站。确保您的网站的内容安全策略 (CSP) 允许 CMS URL 作为 `frame-ancestors`（默认值为 'http://localhost:8000'）。检查编辑器控制台是否有任何错误。

package/zh/intlayer_with_angular.md

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/intlayer_with_vite+preact.md