FastGPT 文档国际化机制从中文 MDX 到北美风格英文文档的双文件 i18n 工作流【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPTFastGPT 的官方文档站采用「中文为源语言、英文为目标语言」的双文件国际化i18n方案其翻译规范被沉淀为一个可复用的 Skill 定义.agents/skills/doc/i18n/SKILL.md并与产品 UI 的术语库共享同一套「唯一事实来源」。阅读本文后你将掌握 FastGPT 文档中英文双文件的目录约定、.mdx内容文件的翻译边界哪些必须保持原样、哪些必须翻译、meta.json导航文件的同步规则以及以Dataset、Collection等共享词库为准绳的北美风格英文写作原则。双文件 i18n 方案与文档目录结构FastGPT 文档站基于 fumadocs-mdx 构建文档内容位于document/content/目录下按guide/、self-host/、openapi/、faq/、plugin/等分类子目录组织。每个页面的国际化通过并排双文件实现而非在单文件内维护多语言内容文件类型中文源文件英文目标文件内容文件{name}.mdx{name}.en.mdx导航文件meta.jsonmeta.en.json例如document/content/guide/getting-started/目录下同时存在index.mdx与index.en.mdx两个内容文件以及meta.json与meta.en.json两个导航文件。Skill 明确定义了翻译方向任务是生成或更新英文文件中文文件始终作为源语言参照翻译目标是「自然流畅的北美英文而非逐字直译」。底层渲染支撑frontmatter 与导航 schema在 source.config.ts 中可以看到文档站的 fumadocs 配置通过defineDocs指定content目录并用 Zod 扩展了 frontmatter schematitle默认Untitled、releaseTime、sidebarTag、upgradeTags等字段。这也解释了翻译规则中「frontmatter 的title和description需要翻译」的来源——它们是页面 SEO 与侧边栏展示的直接输入属于用户可见文本。此外该配置还内置了一个remarkMermaid插件将 bash git diff --name-only git diff --cached --name-only对两条命令的输出进行如下筛选 - 只关注 document/ 目录下的变更文件 - 保留 .mdx 文件排除 .en.mdx和 meta.json排除 meta.en.json - 检查每个命中的中文文件是否有对应的英文文件、英文文件是否需要更新。 **手动指定**用户直接给出文件路径或目录。 无论采用哪种方式Skill 都强制了一条约束**只要翻译范围包含 .mdx 内容文件就必须把同目录的 meta.json / meta.en.json 纳入检查范围**避免新增英文内容后侧边栏导航缺失。 ### 第二步翻译内容文件.mdx → .en.mdx 对每个中文 .mdx 文件生成或更新对应的 .en.mdx 文件。核心匹配规则是**翻译前先按最长中文词组匹配共享词库**。例如 知识库引用 必须整体匹配为 Dataset citation(s)不能拆成 知识库→ Dataset和 引用→ Citation分别处理后再拼接。根据文档语法可以调整大小写和单复数但不得改用词库列出的禁用译法。 **保持不变的部分** - MDX import 语句如 import { Alert } from /components/docs/Alert - 图片路径如  - 链接 URL保持原始 URL 不变 - HTML/JSX 组件结构和属性如 Alert icon contextsuccess - 表格的 markdown 结构 - 代码块内容除非是中文注释 - emoji 符号 **需要翻译的部分** - frontmatter 的 title 和 description - 所有正文文本内容 - 组件内的文本内容如 Alert 内的文字 - 表格中的文字内容 - 代码块中的中文注释 这一划分体现了「翻译用户可见文本、保护机器可见结构」的原则MDX 中的 import、JSX 属性、URL 都是编译期/渲染期的关键标识符任何改动都会导致文档站构建失败或资源 404。 ### 第三步同步导航文件meta.json → meta.en.json 对每个中文 meta.json生成或更新对应的 meta.en.json。翻译 .mdx 文件时还要同步检查其同目录的导航文件规则如下 1. 如果同目录存在 meta.json检查本次翻译的中文文件 basename如 41503.mdx → 41503是否在 pages 数组中 2. 如果中文文件是新增页面且 meta.json 未引用应按目录内现有排序和上下文更新 meta.json无法可靠判断插入位置时先询问用户不要只创建 .en.mdx 后忽略导航 3. meta.en.json 的 pages 必须与 meta.json 保持一致只翻译 title、description 和分隔符字符串**不要翻译或删除页面文件名引用** 4. 如果 meta.en.json 缺失必须创建如果已存在但 pages 落后于 meta.json必须同步 5. 如果用户只指定了 meta.json仍按导航文件翻译规则更新 meta.en.json并检查 pages 中引用的中文 .mdx 是否有对应 .en.mdx 6. 修改导航 JSON 时优先使用结构化 JSON 方式或严格保持原文件格式避免手改导致尾逗号、缩进漂移或 pages 顺序错误。 用仓库中的真实文件可以直观理解「哪些字段翻译、哪些不动」 [meta.json](https://link.gitcode.com/i/5c0474d4b6c129d6ce55398ef0d7da48) json { title: 入门, root: false, pages: [ index, quick-start, [视频教程](https://video.fastgpt.cn/videos), [最佳案例](https://solutions.fastgpt.cn/) ] }meta.en.json{ title: Getting Started, root: false, pages: [ index, quick-start, [Video Tutorials](https://video.fastgpt.cn/videos), [Best Practices](https://solutions.fastgpt.cn/) ] }对照可见title被翻译pages中的页面文件名引用index、quick-start与 URL 保持原样仅翻译 markdown 链接的展示文本[视频教程]→[Video Tutorials]root等结构化字段不变。第四步翻译完成后的复核对照中文源文和共享词库复核所有产品术语发现禁用译法时必须修正搜索英文文件中的残留汉字并逐项确认是品牌名、代码示例还是漏译对词库中的语境词进行人工复核例如训练应按功能使用Indexing、Processing或Reindex而不是机械地译为Training如果遇到词库未收录且会影响产品概念一致性的术语先向用户报告并确认推荐译法不要自行固化新术语输出清单列出所有已翻译的文件以及所有已更新或确认无需更新的meta.json/meta.en.json如果发现有中文文件对应的英文文件缺失提醒用户如果中文.mdx未被同目录meta.json引用且本次未能安全更新导航必须明确提醒用户。翻译原则面向北美开发者的英文写作这些原则的核心目标是让北美开发者读起来感觉像是原生英文文档而不是翻译过来的。语言风格面向北美开发者使用自然的美式英语技术写作风格不要逐字翻译要传达原文的意思和意图技术文档倾向简洁直接避免冗余修饰中文文档常用的排比、铺陈手法翻译时应精简为英文读者习惯的表达。Skill 给出的对照示例中文可轻松导入各式各样的文档及数据能自动对其开展知识结构化处理工作。 ✗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技术术语FastGPT 产品概念必须使用共享专有名词库不得因为现有文档或竞品采用其他叫法而替换。例如知识库→Dataset不是Knowledge Base数据集→Collection不是Dataset节点、模块→Node不是Module调试→Debug试运行→Test Run引用→Citation知识库引用→Dataset citation(s)问题优化→Query rewriting索引模型→Embedding model。词库未覆盖的纯技术概念使用业界通用术语例如LLM、Vector Store、Low-code。如需参考 n8n 或 Dify 的用词只能比较底层产品含义FastGPT 共享词库始终优先。语气保持专业但友好的语气和原文档的风格一致不要过度正式也不要过于随意面向开发者和技术用户假设读者有基本的技术背景。共享词库产品术语的唯一事实来源Skill 在开头即声明开始翻译前必须完整阅读并遵守共享规则且「共享词库是产品术语的唯一事实来源优先级高于现有英文文档、同类产品用词和通用技术习惯。不要在本 Skill 中维护第二套产品词表」。这两份共享资源为产品翻译规范FastGPT 专有名词库词库结构fastgpt-glossary.json 是一个结构化 JSON当前版本为version: 3主要由四部分构成instructions词库使用规则明确「词库优先于现有 locale 文本和竞品术语」「先匹配最长的中文词使复合词优先于其组成部分」「保留规范拼写仅按句子调整大小写与单复数」「当源词出现在同一值中时出现禁用 locale 术语即为错误」terms核心英文术语表每条包含zh一个或多个中文源词、en一个或多个规范英文译法、forbidden禁用译法列表与可选的note语境说明。例如知识库的规范译法是Datasetforbidden为[Knowledge Base, KB]数据集的规范译法是Collection而Dataset反而是它的禁用译法——这解释了为什么 FastGPT 的层级命名Dataset 内包含 Collection与许多同类产品的习惯相反翻译时必须严格按词库执行localeGlossaries按目标语言分列的扩展术语表如ko-KR、zh-Hant结构与terms类似但使用target字段供多语言 UI 场景复用contextOverrides上下文覆盖规则允许同一个中文词在特定命名空间路径下采用不同译法。词库中收录了这样一个例子app命名空间下apply_code路径中的应用是「应用代码Apply」动作而非 FastGPT 的App实体因此该位置应译为Apply。禁用译法与「最长词组匹配」的自动实现词库的匹配规则并非停留在文档层面——同目录的校验脚本 validate-namespace.mjs 把这两条核心原则实现为可执行逻辑可作为理解该机制的最佳参照最长词组优先getGlossaryMatches函数先收集源值中所有词库词条的匹配区间再按sourceTerm.length降序排序仅保留互不重叠的匹配。这正是「知识库引用整体命中后知识库与引用的独立规则不再覆盖其子区间」的程序化表达禁用译法即错误脚本对en目标值在剔除{{插值}}与 URL 等受保护 token 后执行forbidden列表的正则匹配命中即输出Forbidden glossary translation错误规范译法缺失则输出Canonical glossary term may be missing警告残留汉字检测脚本用 Unicode 属性正则\p{ScriptHan}检查en文件中残留的汉字并逐条给出警告与 Skill「搜索英文文件中的残留汉字逐项确认是品牌名、代码示例还是漏译」的人工复核步骤相互印证。该脚本原本服务于 UI locale JSON 的翻译校验见 i18n-translate SKILL运行方式形如node .agents/skills/system/i18n-translate/scripts/validate-namespace.mjs packages/web/i18n/zh-CN/namespace.json但其术语匹配与禁用检查逻辑与文档翻译的人工复核原则完全一致——两者共享同一个词库文件这正是「不维护第二套产品词表」的具体落地。与其他国际化机制的关系从源码结构看FastGPT 仓库的国际化至少包含两条并行的流水线它们在术语层面收敛于同一词库维度文档 i18n本文主题UI locale i18n对象document/content/下的.mdx/meta.jsonpackages/web/i18n/zh-CN/下的 i18next 命名空间 JSON方向中文 → 英文北美风格中文 → 所有兄弟 locale 目录en、zh-Hant等命名约定{name}.mdx/{name}.en.mdxzh-CN/ns.json与同目录各 locale 的同名文件触发方式中文文档新增/修改后同步英文版显式调用$i18n-translate并指定命名空间共享资产翻译规范 专有名词库 「最长词组匹配 / 禁用译法」原则同左两者的边界是明确的文档 Skill 负责面向读者的 MDX 内容标题、正文、表格、代码注释locale Skill 负责面向运行时界面的插值字符串{{count}}、富文本标签、JSON 键序等不可变结构。理解这一区分可以避免把 UI 文案的翻译规则如保留插值符错误地套用到文档翻译上反之亦然。关键文件速查文件作用.agents/skills/doc/i18n/SKILL.md文档中英翻译 Skill 的完整工作流定义本文主体.agents/skills/system/i18n-translate/references/translation-guidelines.md共享的产品翻译风格与术语决策规则.agents/skills/system/i18n-translate/references/fastgpt-glossary.json产品术语唯一事实来源规范译法 禁用译法 上下文覆盖.agents/skills/system/i18n-translate/scripts/validate-namespace.mjs术语与结构校验脚本实现最长匹配与禁用译法检查document/content/文档内容目录中文.mdx与英文.en.mdx并排存放document/source.config.tsfumadocs-mdx 配置frontmatter/meta.jsonschema、Mermaid 组件化转换document/content/guide/getting-started/meta.json与 meta.en.json中英导航文件的最小可对照示例掌握以上内容后你即可按照 Skill 的四步流程独立完成 FastGPT 文档的英文同步用 git diff 圈定范围、按「保护结构、翻译可见文本」的边界产出.en.mdx、保持pages一致性同步meta.en.json并以共享词库为最终裁决标准完成术语复核。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考