# Doc I18n

将 FastGPT 文档从中文翻译为面向北美用户的英文。当用户提到翻译文档、i18n、国际化、translate docs、新增/修改了中文文档需要同步英文版时，使用此...

- Repository: https://github.com/labring/FastGPT (29968 stars)
- Category: Writing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add labring/FastGPT --skill doc-i18n -g -a claude-code -y`
Codex: `npx skills add labring/FastGPT --skill doc-i18n -g -a codex -y`
Cursor: `npx skills add labring/FastGPT --skill doc-i18n -g -a cursor -y`
Gemini CLI: `npx skills add labring/FastGPT --skill doc-i18n -g -a gemini-cli -y`

## Description

将 FastGPT 文档从中文翻译为面向北美用户的英文。当用户提到翻译文档、i18n、国际化、translate docs、新增/修改了中文文档需要同步英文版时，使用此 skill。也适用于用户要求检查文档翻译缺失、批量翻译、或对比中英文文档差异的场景。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 概述

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

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

- [FastGPT 产品翻译规范](../../system/i18n-translate/references/translation-guidelines.md)
- [FastGPT 专有名词库](../../system/i18n-translate/references/fastgpt-glossary.json)

共享词库是产品术语的唯一事实来源，优先级高于现有英文文档、同类产品用词和通用技术习惯。不要在本 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` 文件时，也要同步检查其同目录导航文件：

The rest: https://github.com/labring/FastGPT/blob/HEAD/.agents/skills/doc/i18n/SKILL.md