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.jsonall被解析为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]...、URLhttps?://...、printf 格式符%s/%d等以及真实换行与字面\n目标值与源值这些令牌必须逐项完全一致否则报错。术语表匹配算法getGlossaryMatches()第 96-119 行在源文本中找出所有命中的中文术语按“术语长度降序、位置升序”排序后做非重叠贪心选择确保复合词优先生效、组件规则不会覆盖已批准的复合术语。禁止词守卫对每个命中术语先查找contextOverrides命名空间 路径 源术语三重匹配再对目标文本执行“去除插值与 URL 后”的英文/本地化禁止词检测命中forbidden列表即报错。规范词缺失告警目标文本若未包含该术语任一规范译法产生 warning提醒不阻断。英文残留汉字检查对en目标凡包含汉字/\p{ScriptHan}/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。典型示例中文规范英文禁止备注知识库DatasetKnowledge Base, KB顶层知识库实体数据集 / 集合CollectionDatasetFastGPT 中“数据集”指知识库内的集合知识库引用Dataset citationDataset reference, Knowledge Base citation复数 UI 标签用 Dataset citations智能体AgentBot, AssistantAgent 是特定 App 类型应用AppApplication产品统称实体节点 / 模块NodeModuleFastGPT 产品 UI 只有 Node 概念调试DebugTest Run与“试运行 Test Run”严格区分试运行Test RunDebug运行测试语义工作流WorkflowFlow—工作台StudioWorkbench—结果重排RerankingResult rearrangement—索引模型Embedding modelIndex model避免直译误导对话ChatDialogue完整交互对象可用 Conversation发布PublishRelease发布动作/状态训练Indexing / Reindex / ProcessingTraining知识库处理管道语义此外还有品牌名规范飞书→Lark、语雀→Yuque、钉钉→DingTalk保留官方拼写并在句子中适配大小写与单复数。语种专属术语localeGlossarieslocaleGlossaries.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 applicationCreate app工作流运行失败请重试Workflow operation failed, please retryWorkflow failed. Try again.暂无数据There is no data for nowNo data yet选择需要使用的知识库Select the knowledge base that needs to be usedSelect a Dataset开启后即可使用After opening, it can be usedTurn this on to use the feature.每个示例都要按真实 UI 角色判断页面标题、按钮、tooltip 与错误提示即使中文相近措辞也可能不同。工程实践小结从这条技能可以提炼出可复用的多语言工程方法论单一真源SSOT以简体中文为唯一源避免多语种互相翻译导致的语义漂移术语先行用带禁止词的术语表约束规范译法复合词最长匹配优先从根本上杜绝同词多译自动化闸门通过展平路径比对、受保护令牌比对、术语命中检测与多余键/缺失键检查把“结构正确 术语正确”变成可重复执行的校验命令而非人工自觉范围克制只动被选中的命名空间保留无关修改绝不越权新建语种或改动其他命名空间人机分工机器保证结构与术语人工通过git diff复查措辞、大小写与残留中文最终形成闭环。参考上述流程任何人都可以在本地仓库中通过$i18n-translate技能显式触发一次规范、可验证、可追溯的 FastGPT 命名空间翻译任务。【免费下载链接】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），仅供参考