Doc I18n

概述

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

开始翻译前，必须完整阅读并遵守以下共享规则：

• FastGPT 产品翻译规范
• FastGPT 专有名词库

共享词库是产品术语的唯一事实来源，优先级高于现有英文文档、同类产品用词和通用技术习惯。不要在本 Skill 中维护第二套产品词表。

文件结构

文档位于 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 文件。

翻译前先按最长中文词组匹配共享词库。例如，知识库引用 必须整体匹配为 Dataset citation(s)，不能拆成 知识库 和 引用 分别处理。根据文档语法调整大小写和单复数，但不得改用词库列出的禁用译法。

保持不变的部分：

• MDX import 语句（如 import { Alert } from '@/components/docs/Alert'）
• 图片路径（如 ![](/imgs/intro/image1.png)）
• 外部链接及共享静态资源 URL（站内文档链接的语言前缀按下方规则处理）
• HTML/JSX 组件结构和属性（如 <Alert icon="🤖" context="success">）
• 表格的 markdown 结构
• 代码块内容（除非是中文注释）
• emoji 符号

英文站内文档链接：

• 指向英文文档的站内绝对路径必须保留或补齐 /en/ 前缀。例如，中文的 /guide/build/workflow/assisted-generation 对应英文的 /en/guide/build/workflow/assisted-generation；更新既有英文页时，不要为对齐中文 URL 而移除该前缀。
• LocalizedLink 会在浏览器渲染时补齐语言前缀，但 document/script/checkEnglishDocs.mjs 直接按原始 href 查找英文路由，不经过该组件。因此，浏览器跳转正常不能代替英文路由校验。
• 外链、/imgs/... 等共享静态资源及纯锚点保持原始 URL。站内文档链接需核实英文目标页面及其锚点；核对双语链接时允许语言前缀和翻译后锚点的差异，不要求原始 href 逐字相同。

需要翻译的部分：

• frontmatter 的 title 和 description
• 所有正文文本内容
• 组件内的文本内容（如 Alert 内的文字）
• 表格中的文字内容
• 代码块中的中文注释

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

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