doc-i18n

## 概述

FastGPT 文档采用双文件 i18n 方案，中文为源语言，英文为目标语言。你的任务是将中文文档翻译为自然流畅的北美英文，而非逐字直译。

## 文件结构

文档位于 `document/content/` 目录下，可能分布在 `docs/`、`self-host/` 等子目录：

- 内容文件：`{name}.mdx`（中文） → `{name}.en.mdx`（英文）
- 导航文件：`meta.json`（中文） → `meta.en.json`（英文）

## 工作流程

### 1. 确定翻译范围

两种方式确定需要翻译的文件：

**自动检测**（用户未指定具体文件时）：
- 运行 `git diff --name-only` 和 `git diff --cached --name-only` 检测 `document/` 下变更的中文文件
- 筛选出 `.mdx`（排除 `.en.mdx`）和 `meta.json`（排除 `meta.en.json`）
- 检查对应的英文文件是否存在或是否需要更新

**手动指定**：用户直接给出文件路径或目录。

无论使用哪种方式，只要翻译范围包含 `.mdx` 内容文件，都必须把同目录的 `meta.json` / `meta.en.json` 纳入检查范围，避免新增英文内容后导航缺失。

### 2. 翻译内容文件（.mdx → .en.mdx）

对每个中文 `.mdx` 文件，生成或更新对应的 `.en.mdx` 文件。

**保持不变的部分**：
- MDX import 语句（如 `import { Alert } from '@/components/docs/Alert'`）
- 图片路径（如 `![](/imgs/intro/image1.png)`）
- 链接 URL（保持原始 URL 不变）
- HTML/JSX 组件结构和属性（如 `<Alert icon="🤖" context="success">`）
- 表格的 markdown 结构
- 代码块内容（除非是中文注释）
- emoji 符号

**需要翻译的部分**：
- frontmatter 的 `title` 和 `description`
- 所有正文文本内容
- 组件内的文本内容（如 Alert 内的文字）
- 表格中的文字内容
- 代码块中的中文注释

### 3. 同步导航文件（meta.json → meta.en.json）

对每个中文 `meta.json`，生成或更新对应的 `meta.en.json`。翻译 `.mdx` 文件时，也要同步检查其同目录导航文件：

- 如果同目录存在 `meta.json`，检查本次翻译的中文文件 basename（如 `41503.mdx` → `41503`）是否在 `pages` 数组中。
- 如果中文文件是新增页面且 `meta.json` 未引用，应按目录内现有排序和上下文更新 `meta.json`；无法可靠判断位置时，先询问用户，不要只创建 `.en.mdx` 后忽略导航。
- `meta.en.json` 的 `pages` 必须与 `meta.json` 保持一致，只翻译 `title`、`description` 和分隔符字符串，不要翻译或删除页面文件名引用。
- 如果 `meta.en.json` 缺失，必须创建；如果已存在但 `pages` 落后于 `meta.json`，必须同步。
- 如果用户只指定了 `meta.json`，仍按导航文件翻译规则更新 `meta.en.json`，并检查 `pages` 中引用的中文 `.mdx` 是否有对应 `.en.mdx`。
- 修改导航 JSON 时优先使用结构化 JSON 方式或严格保持原文件格式，避免手改导致尾逗号、缩进漂移或 `pages` 顺序错误。

**需要翻译的字段**：`title`、`description`、分隔符字符串（如 `"---入门---"` → `"---Getting Started---"`）

**保持不变的字段**：`pages` 数组中的文件名引用、`icon`、`root`、`order`

### 4. 翻译完成后

- 列出所有已翻译的文件
- 列出所有已更新或确认无需更新的 `meta.json` / `meta.en.json`
- 如果发现中文文件有对应英文文件缺失的情况，提醒用户
- 如果发现中文 `.mdx` 未被同目录 `meta.json` 引用，且本次未能安全更新导航，明确提醒用户

## 翻译原则

这些原则的核心目标是让北美开发者读起来感觉像是原生英文文档，而不是翻译过来的。

### 语言风格

- 面向北美开发者，使用自然的美式英语技术写作风格
- 不要逐字翻译，要传达原文的意思和意图
- 技术文档倾向简洁直接，避免冗余修饰
- 中文文档常用的排比、铺陈手法，翻译时应精简为英文读者习惯的表达

**示例**：
```
中文：可轻松导入各式各样的文档及数据，能自动对其开展知识结构化处理工作。
  ✗：You can easily import various documents and data, which will be automatically processed for knowledge structuring.
  ✓：Import documents and data with automatic knowledge structuring.
```

### 中国特有平台和服务的本地化

直接使用国际版名称，不保留中文原名：

| 中文 | 英文 |
|------|------|
| 飞书 | Lark |
| 企业微信 | WeCom |
| 钉钉 | DingTalk |
| 公众号 | WeChat Official Account |
| 文心一言 | ERNIE Bot |
| 中国大陆版 | China Mainland |
| 国际版 | International |

### 技术术语

保持业界通用的英文术语，不要生造翻译：

| 中文 | 英文 |
|------|------|
| 知识库 | Knowledge Base |
| 工作流 | Workflow |
| 大语言模型 | LLM / Large Language Model |
| 向量存储 | Vector Store |
| 可视化编排 | Visual Orchestration |
| 低代码 | Low-code |
| 节点 | Node |
| 插件 | Plugin |

### 语气

- 保持专业但友好的语气，和原文档的风格一致
- 不要过度正式，也不要过于随意
- 面向开发者和技术用户，假设读者有基本的技术背景