FastGPT i18n 多语言命名空间翻译技能：从简体中文源到全语种交付的工程化实践-迪斯科星球

FastGPT 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/FastGPT

导读

本文围绕 FastGPT 仓库中内置的i18n-translate系统级技能（.agents/skills/system/i18n-translate/SKILL.md），完整讲解如何将packages/web/i18n/zh-CN/下以简体中文为“语义与结构唯一真源（source of truth）”的 i18next 命名空间 JSON 文件，批量翻译到en、zh-Hant、ko-KR等目标语种，并在交付前通过仓库自带校验器完成结构与术语的自动验证。读完本文，你将掌握 FastGPT 多语言资源的目录组织、翻译决策依据（产品术语表）、逐语种翻译规范、受保护运行时令牌（插值变量、富文本标签、URL 等）的保全规则，以及结构化校验脚本的底层原理与完整命令用法。

FastGPT 前端国际化架构：命名空间与语种目录

FastGPT 的前端国际化基于 i18next 实现，所有界面文案按“命名空间（namespace）”拆分，分布在 packages/web/i18n/ 下的各语种目录中。每个语种目录内是一组同名同结构的 JSON 文件，例如app.json、dataset.json、workflow.json、common.json等。

源语种目录：packages/web/i18n/zh-CN/，共 29 个命名空间文件（account.json、account_bill.json、apikey.json、app.json、chat.json、common.json、config.json、config_model.json、dataset.json、workflow.json等），是翻译的语义与结构唯一真源。
目标语种目录：packages/web/i18n/en/、packages/web/i18n/zh-Hant/、packages/web/i18n/ko-KR/，各 29 个文件，与源保持一一对应。
命名空间清单：在 packages/web/i18n/constants.ts 中通过I18N_NAMESPACES数组集中声明，共 29 个；任何新增命名空间都需要同步登记在该清单中才会被资源加载器识别。

以packages/web/i18n/zh-CN/app.json为例（约 596 行），其中既有普通文案（"Add_tool": "添加工具"），也包含插值变量（"HTTP_tools_list_with_number": "工具列表: {{total}}"）——这类带占位符的键值正是翻译时必须逐字保全的动态内容。

i18n-translate 技能定位：显式调用、范围受控

.agents/skills/system/i18n-translate/SKILL.md是一个“系统级 Agent 技能”，其设计目标是只做一件事：把用户显式指定的中文命名空间翻译为所有受支持的目标语种。该技能有严格的触发约束（agents/openai.yaml）：

仅当用户显式调用$i18n-translate，并指明命名空间名称、packages/web/i18n/zh-CN/下的具体文件，或all时才会触发；
禁止隐式触发（allow_implicit_invocation: false），日常的文案修改、文档写作不会误触发该技能；
翻译过程不改变任何运行时行为，只做文案层面的语言替换。

核心工作流：五个环节

SKILL.md 将翻译任务拆解为五个明确的环节，每个环节都有可执行的判定标准。

1. 解析并收紧范围（Resolve and constrain the scope）

用户必须显式给出命名空间名、源文件路径或all，不允许模糊指令；
裸命名空间（如app）会被解析为packages/web/i18n/zh-CN/app.json；
all被解析为packages/web/i18n/zh-CN/下按文件名排序的全部JSON 文件；
拒绝非zh-CN来源：翻译必须以简体中文为源，其他语种文件不能作为翻译起点；
目标语种自动发现：扫描packages/web/i18n/下所有兄弟语种目录并排除zh-CN；
只编辑被选中的命名空间文件；当目标语种目录已存在但缺少对应文件时可以新建该文件，但绝不创建新语种目录；
目标文件中已存在的、与本次任务无关的用户修改必须原样保留，不得覆盖。

2. 先确立产品语义，再斟酌措辞（Establish product meaning before wording）

这是该技能与普通“机器翻译”最大的区别：翻译前先确定产品概念的标准译法。操作顺序为：

通读完整中文源文件与所有现存目标文件；
用rg在packages/web/i18n/en/中检索同一产品概念在其他命名空间的既有译法，保持全局一致；
检查调用点（call sites）以判断文本角色：是按钮、标题、状态、描述、Toast 还是校验提示；
按证据优先级决策：FastGPT 术语表 → 功能行为与 UI 上下文 → 邻近翻译风格 → n8n/Dify 官方产品英文语言 → 通用技术用法；
最长术语优先匹配：复合词（如知识库引用）的译法优先级高于其组成词（知识库、引用）各自的译法；
若术语表中缺失某个必要的 FastGPT 产品概念，应上报而非自行发明新规范词；
术语表标记为“禁止”的译法视为错误；当证据冲突无法裁决时，暂停并就具体术语询问用户。

3. 逐语种翻译（Translate locale by locale）

每个目标语种遵循各自的风格约束，但共同遵守结构对齐底线：

结构对齐：JSON 键名、嵌套层级、键顺序、值类型、格式化均与中文源一致；
运行时令牌保全：插值变量（{{name}}）、富文本标签（<bold>）、URL、字面转义序列、有意义的换行结构必须原样保留；
键集合对齐：目标文件的键集合与源完全一致；只有确认某目标专属键在完整源文件中不存在时才能删除，禁止依据局部片段推断；
en（北美产品英语）：简洁自然，翻译“意图”而非“语法”，默认使用 sentence case（句子式大小写），优先熟悉的行业术语而非中式直译；
zh-Hant（繁体中文）：使用中性、自然的繁体中文，而非盲目字符转换；区域性差异出现时优先采用仓库既有术语；
ko-KR（韩语）：遵循fastgpt-glossary.json中localeGlossaries.ko-KR定义的规范韩语术语；
未来语种：使用该语种的原生产品语言；若无法获得可靠翻译，应暂停并询问用户是跳过该语种还是等待合格审校，不得静默交付残缺语种集；
同一产品概念尽量复用一个译法，除非 UI 上下文确实改变了语义；若在指定命名空间之外发现同一术语翻译不一致，上报但未经用户同意不得改动其他命名空间。

4. 交付前校验（Validate before finishing）

在仓库根目录运行内置校验器，对选中的命名空间逐一校验：

node .agents/skills/system/i18n-translate/scripts/validate-namespace.mjs \ packages/web/i18n/zh-CN/<namespace>.json

单命名空间：运行一次，要求零错误、零警告；
all模式：对每个源命名空间各运行一次，每次都必须零错误零警告；
随后用仓库格式化器格式化仅被修改的命名空间 JSON 文件；
格式化后再次运行校验器（防止格式化引入偏差）；
通过git diff -- <源与目标文件>人工复查是否存在误译、意外键改动、陈旧值、大小写不一致与无关编辑；
在英文目标中搜索未翻译的汉字文本；合法的中文品牌名或面向用户展示的示例视为“已审阅例外”，不自动判失败；
翻译纯文案变更不运行完整测试套件，除非用户要求或本次改动同时涉及 JSON 之外的代码/配置。

5. 完成汇报（Completion response）

任务完成后必须汇报：翻译的命名空间与语种、创建或更新的文件、执行的校验命令及结果、有意保留的源语言文本或未决术语。且不额外撰写总结文档，避免污染仓库。

校验器源码解析：结构对齐与术语守卫如何实现

scripts/validate-namespace.mjs 是整套流程的“质量闸门”，理解其实现能帮助你预判任何一次校验的通过条件。

用法：

# 校验指定源文件在全部兄弟语种目录中的对应文件 node .agents/skills/system/i18n-translate/scripts/validate-namespace.mjs <zh-CN-source.json> # 指定部分目标文件 node .agents/skills/system/i18n-translate/scripts/validate-namespace.mjs <zh-CN-source.json> [target.json ...]

核心实现要点：

来源约束：脚本通过path.basename(path.dirname(sourcePath))校验源文件必须位于zh-CN目录下，否则直接报错退出（见第 17-24 行）。
键路径展平：flatten()函数（第 34-52 行）把嵌套 JSON 递归展开为“路径 → {类型, 值}”的 Map，路径形如$、key、key.sub、key[0]，从而对任意深度的键进行逐项比对。
目标发现：未显式指定目标时，discoverTargets()（第 124-133 行）读取语种根目录下除zh-CN外的全部目录作为目标集合。
受保护令牌比对：collectProtectedTokens()（第 62-69 行）从字符串值中分别提取插值（{{-?\s*[^{}]+?\s*}}）、HTML 富文本标签（</?[A-Za-z]...>）、URL（https?://...）、printf 格式符（%s/%d等）以及真实换行与字面\n，目标值与源值这些令牌必须逐项完全一致，否则报错。
术语表匹配算法：getGlossaryMatches()（第 96-119 行）在源文本中找出所有命中的中文术语，按“术语长度降序、位置升序”排序后做非重叠贪心选择，确保复合词优先生效、组件规则不会覆盖已批准的复合术语。
禁止词守卫：对每个命中术语，先查找contextOverrides（命名空间 + 路径 + 源术语三重匹配），再对目标文本执行“去除插值与 URL 后”的英文/本地化禁止词检测；命中forbidden列表即报错。
规范词缺失告警：目标文本若未包含该术语任一规范译法，产生 warning（提醒，不阻断）。
英文残留汉字检查：对en目标，凡包含汉字（/\p{Script=Han}/u）的值都会告警，并区分“与源完全相同（未翻译）”与“含汉字”两种原因。
多余键检测：目标中存在但源中不存在的键路径会直接报Extra path not present in zh-CN（第 280-284 行），反过来源有目标无则报Missing path（第 179-184 行）。
键顺序校验：当双方路径集合一致时，还会用JSON.stringify比较顺序，顺序不一致同样报错（第 171-177 行）。

术语表体系：翻译决策的“宪法”

references/fastgpt-glossary.json（当前版本version: 3）是整个翻译体系的核心资产，分为三个层次：

通用英文术语（terms）

每条记录包含中文原文（zh，可多个同义词）、规范英文（en，可多个变体）、禁止词（forbidden）与备注（note）。典型示例：

中文	规范英文	禁止	备注
知识库	Dataset	Knowledge Base, KB	顶层知识库实体
数据集 / 集合	Collection	Dataset	FastGPT 中“数据集”指知识库内的集合
知识库引用	Dataset citation	Dataset reference, Knowledge Base citation	复数 UI 标签用 Dataset citations
智能体	Agent	Bot, Assistant	Agent 是特定 App 类型
应用	App	Application	产品统称实体
节点 / 模块	Node	Module	FastGPT 产品 UI 只有 Node 概念
调试	Debug	Test Run	与“试运行 Test Run”严格区分
试运行	Test Run	Debug	运行测试语义
工作流	Workflow	Flow	—
工作台	Studio	Workbench	—
结果重排	Reranking	Result rearrangement	—
索引模型	Embedding model	Index model	避免直译误导
对话	Chat	Dialogue	完整交互对象可用 Conversation
发布	Publish	Release	发布动作/状态
训练	Indexing / Reindex / Processing	Training	知识库处理管道语义

此外还有品牌名规范（飞书→Lark、语雀→Yuque、钉钉→DingTalk），保留官方拼写并在句子中适配大小写与单复数。

语种专属术语（localeGlossaries）

localeGlossaries.ko-KR（约 50 条）与localeGlossaries.zh-Hant为特定语种定义独立于英文的术语与禁止词。例如韩语中强调Dataset（데이터셋）与其中 Collection（컬렉션）的层级区分；知识库→데이터셋（禁止지식베이스），插件市场→마켓플레이스（禁止플러그인 마켓）。

上下文覆盖（contextOverrides）

用于处理“同一中文词在不同命名空间路径下语义不同”的情况，例如app命名空间下的apply_code路径中，应用是“应用（生成的代码）”这一动作，应译为Apply（韩语적용）而非产品实体App。

翻译风格指南：让界面“为市场而写”

references/translation-guidelines.md 定义了英文目标的写作规范，核心原则是“让界面看起来像是为目标市场原生撰写，而非从中文翻译而来”：

英文风格：当代北美产品英语；UI 文案短小具体，去掉中文冗余词（“进行”“相关”“即可”及多余 please）；按钮/标签/标题/状态默认 sentence case；动作用祈使句（Create app、Retry、Select a Dataset），字段与导航用名词短语（Model provider、Usage details）；错误文案先陈述问题再给出恢复动作（Upload failed. Try again.）；自然使用缩略词但避免俚语；优先you/your而非被动与官僚化措辞；不得添加源文中不存在、产品不支持的任何承诺、限制或解释。
参照系：当工作流、Agent、节点、执行、凭证、插件或知识类术语存疑时，可参考 n8n 与 Dify 的官方英文文档/产品 UI，但仅对比底层行为而非照抄中文标签，且概念与用户动作匹配才采纳，FastGPT 既有清晰一致的术语优先。
运行时不变量：JSON 键与其顺序、插值名称与定界符（{{count}}）、富文本标签名与结构（<bold>...</bold>）、URL、文件扩展名、命令名、代码、协议名与标识符、有意义的换行结构与字面\\n、数字限制/单位/功能行为——一律不译不改；富文本标签内部文字要翻译，标签本身保留；同时保留%、MB、tokens、points、requests、records 等单位的语义区分。
上下文敏感示例：

中文	避免	优先
创建应用	Create an application	Create app
工作流运行失败，请重试	Workflow operation failed, please retry	Workflow failed. Try again.
暂无数据	There is no data for now	No data yet
选择需要使用的知识库	Select the knowledge base that needs to be used	Select a Dataset
开启后即可使用	After opening, it can be used	Turn this on to use the feature.

每个示例都要按真实 UI 角色判断：页面标题、按钮、tooltip 与错误提示即使中文相近，措辞也可能不同。

工程实践小结

从这条技能可以提炼出可复用的多语言工程方法论：

单一真源（SSOT）：以简体中文为唯一源，避免多语种互相翻译导致的语义漂移；
术语先行：用带禁止词的术语表约束规范译法，复合词最长匹配优先，从根本上杜绝同词多译；
自动化闸门：通过展平路径比对、受保护令牌比对、术语命中检测与多余键/缺失键检查，把“结构正确 + 术语正确”变成可重复执行的校验命令而非人工自觉；
范围克制：只动被选中的命名空间，保留无关修改，绝不越权新建语种或改动其他命名空间；
人机分工：机器保证结构与术语，人工通过git diff复查措辞、大小写与残留中文，最终形成闭环。

参考上述流程，任何人都可以在本地仓库中通过$i18n-translate技能显式触发一次规范、可验证、可追溯的 FastGPT 命名空间翻译任务。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析