Cocos Creator 编辑器国际化i18n文件规范与合并机制深入解析【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine导读本文基于 Cocos Creator 引擎仓库中 editor/i18n/README.md 的工程约定系统讲解编辑器内置英文/中文文案的组织方式、自动合并原理以及新增模块国际化文件的推荐写法。你将掌握ENGINE.i18n数据表的分层结构、CommonJS 模块的命名约束、通过mixin与link实现的数据合并与继承机制并学会如何在 Cocos Creator 编辑器中为一个新模块添加多语言文案同时了解该机制在属性检查器Inspector、动画图Pose Graph拖拽菜单等场景中的实际消费方式。一、为什么需要编辑器 i18n从一份 README 说起的工程约定editor/i18n/README.md 全文以注释形式给出了三条核心工程约定编辑器已经自动合并了ENGINE命名空间下en与zh目录内所有文件的数据因此目录下的各数据文件之间不需要再互相require避免了文件间的隐式依赖与加载顺序问题新模块xxx的 i18n 只需要新增一个文件文件内容遵循module.exports { xxx: {} }的约定其余交给编辑器自动合并。这份 README 实际上定义了 Cocos Creator 编辑器中“引擎侧文案”的扩展入口。与此对应仓库中存在两套语言资源目录editor/i18n/en英文文案包含animation.js、assets.js、components.js、localization.js以及 modules 子目录 下的physics.js、rendering.js、terrain.js、ui.jseditor/i18n/zh中文文案目录结构完全对称。其中animation.js、ui.js等文件服务于动画、UI 等引擎模块的属性检查器文案而 modules 目录 则按模块拆分放置特定功能如物理、渲染、地形、UI的增量文案正好对应 README 中“新模块新增文件”的实践——modules/ui.js与modules/rendering.js就是模块化拆分后的实际示例。二、i18n 数据的目录结构与文件形态2.1 目录骨架editor/i18n/ ├── README.md # 本文档三条合并约定 ├── en/ │ ├── animation.js │ ├── assets.js │ ├── components.js │ ├── localization.js │ └── modules/ │ ├── physics.js │ ├── rendering.js │ ├── terrain.js │ └── ui.js └── zh/ # 与 en 完全对称的中文资源 ├── animation.js ├── assets.js ├── components.js ├── localization.js └── modules/…2.2 文件形态CommonJS 模块所有文案文件都是 CommonJS 模块通过module.exports导出一个嵌套对象。以 editor/i18n/en/modules/ui.js 为例/* eslint-disable quote-props */ module.exports { classes: { cc: { UIRenderer: { properties: { customMaterial: { displayName: Custom Material, tooltip: Use custom material., }, color: { displayName: Color, tooltip: Rendering color., }, }, }, Label: { properties: { __extends__: classes.cc.UIRenderer.properties, string: { displayName: string, tooltip: The label text., }, // ... }, }, }, }, };值得注意的几点每个属性条目通常携带两个字段displayName属性面板上的显示名与tooltip悬停提示。顶层classes之下以cc作为命名空间再按组件类名如Label、Sprite逐层展开这一结构与引擎 cocos/2d、cocos/ui 等模块的组件类定义一一对应。除cc外还有第三方命名空间如spSpine下的Skeleton组件其文案同样挂载在classes.sp.Skeleton下。文件头部通过/* eslint-disable quote-props */等注释关闭引号与命名风格校验因为键名大量包含非标识符字符如cc、点号路径。三、自动合并机制editor/i18n-utils.js 的实现原理README 中“编辑器自动合并”并非魔法其底层实现就位于 editor/i18n-utils.js。该文件导出两个核心函数mixin与link。3.1 mixin深合并mixin(result, ...args)将多个源对象按序深合并进result规则如下标量冲突报错当源对象中某个键在目标中已存在且值类型不可合并时会调用reportMixinFailure打印Can not mix ... into ...并给出两侧的完整路径与类型string/object/array/null便于定位冲突数组合并目标与源的同一键若都是数组则执行push(...)拼接而非覆盖对象递归普通对象则递归进入mixinObject逐层合并。3.2 link按引用路径展开继承link(root)处理各文件中出现的__extends__字段。其实现要点遍历对象树遇到__extends__: classes.cc.Animation.properties之类的字符串时按点号路径在根对象内查找目标find函数逐段in校验找不到会打印Can not find the __extends__ ...找到后先递归link目标保证其自身的__extends__也被展开再通过mixinObject把基类内容合并进当前对象对每个访问过的对象用visited集合去重防止循环引用导致死循环。这一机制让子类组件无需重复书写父类全部属性文案。典型的继承链如editor/i18n/en/animation.jsSkeletalAnimation.properties通过__extends__: classes.cc.Animation.properties继承Animation的全部属性文案editor/i18n/en/modules/ui.jsLabel、Sprite、sp.Skeleton共同继承UIRenderer.propertieseditor/i18n/en/animation.jsPoseNodeBlendTwoPose、PoseNodeFilteringBlend通过__extends__复用PoseNodeBlendTwoPoseBase.inputs的输入插槽文案。配合mixin使用时的典型调用形如link(mixin({...}, extra))即先把多个数据源合并成一张表再一次性解析所有继承引用这正是 editor/i18n/en/localization.js 与 editor/i18n/zh/localization.js 顶部module.exports link(mixin({...}))的写法。3.3 版本号注入editor/i18n/en/localization.js 还展示了另一个细节通过require(../../../package.json)读取引擎版本用pkg.version.replace(/(^\d\.\d)\..*$/, ...)截取主次版本号如3.8并拼进文档链接模板https://docs.cocos.com/creator得到help文案中的手册地址。这保证了属性面板中的帮助链接始终指向与当前引擎版本匹配的文档页。需要注意的是文档中出现的这些外部帮助链接属于引擎运行时生成的跳转数据正文引用请以仓库内 editor/i18n/zh/localization.js 源码为准。四、按 README 约定新增一个模块的国际化文件以 README 给出的“新模块xxx”为例标准步骤是在 editor/i18n/en 与 editor/i18n/zh 下各新增一个文件例如xxx.js文件内容只需module.exports { xxx: {} }编辑器加载时会自动把en与zh下的所有文件合并进ENGINE命名空间因此不要在这些文件之间互相require在xxx对象内按业务需要填充字段例如属性面板文案建议沿用classes.cc.xxx.properties的结构动画图节点可参考animation_graph与createPoseNodeOnAssetDragHandler的既有命名。仓库中已有的模块化范例editor/i18n/en/modules/ui.jsUIRenderer、Label、RichText、Sprite、UISkew以及sp.Skeleton的属性面板文案editor/i18n/en/modules/rendering.js渲染相关组件的属性文案其中MeshRenderer同样使用了__extends__继承机制见 en/modules/rendering.jseditor/i18n/zh/modules/physics.js、editor/i18n/zh/modules/terrain.js物理与地形模块的中文文案。五、文案数据在编辑器中的消费方式5.1 组件属性检查器Inspectorclasses.cc.*.properties下的displayName与tooltip会被属性面板Inspector读取并渲染。例如在 editor/i18n/en/animation.js 中cc.Animation.propertiesclips组件管理的所有剪辑、defaultClip默认播放的剪辑、playOnLoad加载后是否自动播放cc.SkeletalAnimation.propertiessockets挂点列表需先注册才能把自定义节点挂到动画骨骼上、useBakedAnimation预烘焙动画默认开启可大幅提升性能但会固定所有动画效果。这些英文文案在 editor/i18n/zh/animation.js 中有严格对应的中文译文编辑器按当前语言环境选择其一渲染。5.2 动画图Marionette / Pose Graph菜单与拖拽animation_graph与classes.cc.animation.*下的文案服务於动画状态机与姿态图编辑界面pose_graph_node_sub_categories姿态图节点创建菜单的子分类名姿态节点、混合、反向动力学、选择pose_graph_node_sub_menus子菜单项播放/采样动画剪辑、一维/二维动画混合PoseNodePlayMotion、PoseNodeSampleMotion等节点还定义了title模板如播放 {motionName}与createPoseNodeOnAssetDragHandler.displayName后者用于资源拖拽生成节点时的菜单显示文本。这一消费点有源码直接佐证editor/src/marionette/pose-graph/drag/handlers/play-motion.ts 与 sample-motion.ts 中均以i18n:ENGINE.classes.cc.animation.PoseNodePlayMotion.createPoseNodeOnAssetDragHandler.displayName的形式引用即通过i18n:ENGINE.前缀定位到EN/zh合并后数据表中的对应字段。由此可以反推 README 所述“自动合并”的实际作用范围ENGINE即合并后挂载在编辑器 i18n 命名空间上的整棵数据树。5.3 文档帮助链接helpeditor/i18n/en/localization.js 中的help.cc与help.assets为各组件与资源类型提供了指向官方手册的链接模板基于 3.8 版本号生成中文侧 editor/i18n/zh/localization.js 则指向中文手册。编辑器在属性面板的组件帮助按钮、资源类型说明等处消费这些地址。六、多语言字段编写要点总结结合仓库实际文件可提炼出以下可复用的编写准则结构即数据用嵌套对象表达层级顶层xxx为模块命名空间内部按classes/help/features等既定分类组织。features分类见 editor/i18n/zh/localization.js 起的features.categories、physics、gfx_webgl2、gpu_driven等服务于引擎功能裁剪界面描述如 “基于 Bullet 的物理系统支持”。键名保持一致同一文案的键在en与zh中必须完全一致只替换值en与zh目录树保持对称避免某一侧缺失导致回退异常。复用优先于复制子类或同类属性通过__extends__指向共享节点如classes.cc.UIRenderer.properties避免成百上千行重复文案也方便统一修改。使用displayName/tooltip约定字段属性面板条目的显示名与悬停提示分别对应这两个字段对于枚举选项可扩展tooltip_left/tooltip_right等后缀字段见 en/modules/ui.js 中 Label 对齐方式的写法。HTML 拼接提示tooltip中大量使用br换行与列表式说明可在同一字段内展示多行富文本提示。不要互相 require依赖编辑器自动合并模块文件保持彼此独立避免循环依赖与加载顺序问题——这正是 README 的核心结论。七、进阶如何在编辑器之外验证与复用验证合并逻辑mixin与link是纯函数实现见 editor/i18n-utils.js不依赖编辑器运行时可单独用 Node.js 加载require(editor/i18n-utils.js)后传入若干en/zh数据对象做合并测试冲突路径会以Can not mix ...形式打印在控制台。观察版本注入localization.js在构建时读取 package.json 的version字段生成文档链接修改主次版本号会影响帮助链接的指向。配合编辑器资源表引擎的功能裁剪项features同时出现在 editor/engine-features/schema.json、editor/engine-features/render-config.json 等配置中localization.js中的features文案即为其提供多语言标签二者需保持键名同步。结语editor/i18n/README.md虽只有寥寥数行却精准定义了 Cocos Creator 编辑器国际化资源的关键工程规范以模块文件为粒度、以自动合成为手段、以ENGINE命名空间为出口。配合 editor/i18n-utils.js 的mixin/link实现这一机制在保证 en/zh 文案零重复维护的同时支撑了属性检查器、姿态图菜单、功能裁剪面板与文档帮助链接等众多编辑场景。理解这份约定即可按同样的模式为引擎新增模块快速接入多语言文案。【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cocos Creator 编辑器国际化（i18n）文件规范与合并机制深入解析
Cocos Creator 编辑器国际化i18n文件规范与合并机制深入解析【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine导读本文基于 Cocos Creator 引擎仓库中 editor/i18n/README.md 的工程约定系统讲解编辑器内置英文/中文文案的组织方式、自动合并原理以及新增模块国际化文件的推荐写法。你将掌握ENGINE.i18n数据表的分层结构、CommonJS 模块的命名约束、通过mixin与link实现的数据合并与继承机制并学会如何在 Cocos Creator 编辑器中为一个新模块添加多语言文案同时了解该机制在属性检查器Inspector、动画图Pose Graph拖拽菜单等场景中的实际消费方式。一、为什么需要编辑器 i18n从一份 README 说起的工程约定editor/i18n/README.md 全文以注释形式给出了三条核心工程约定编辑器已经自动合并了ENGINE命名空间下en与zh目录内所有文件的数据因此目录下的各数据文件之间不需要再互相require避免了文件间的隐式依赖与加载顺序问题新模块xxx的 i18n 只需要新增一个文件文件内容遵循module.exports { xxx: {} }的约定其余交给编辑器自动合并。这份 README 实际上定义了 Cocos Creator 编辑器中“引擎侧文案”的扩展入口。与此对应仓库中存在两套语言资源目录editor/i18n/en英文文案包含animation.js、assets.js、components.js、localization.js以及 modules 子目录 下的physics.js、rendering.js、terrain.js、ui.jseditor/i18n/zh中文文案目录结构完全对称。其中animation.js、ui.js等文件服务于动画、UI 等引擎模块的属性检查器文案而 modules 目录 则按模块拆分放置特定功能如物理、渲染、地形、UI的增量文案正好对应 README 中“新模块新增文件”的实践——modules/ui.js与modules/rendering.js就是模块化拆分后的实际示例。二、i18n 数据的目录结构与文件形态2.1 目录骨架editor/i18n/ ├── README.md # 本文档三条合并约定 ├── en/ │ ├── animation.js │ ├── assets.js │ ├── components.js │ ├── localization.js │ └── modules/ │ ├── physics.js │ ├── rendering.js │ ├── terrain.js │ └── ui.js └── zh/ # 与 en 完全对称的中文资源 ├── animation.js ├── assets.js ├── components.js ├── localization.js └── modules/…2.2 文件形态CommonJS 模块所有文案文件都是 CommonJS 模块通过module.exports导出一个嵌套对象。以 editor/i18n/en/modules/ui.js 为例/* eslint-disable quote-props */ module.exports { classes: { cc: { UIRenderer: { properties: { customMaterial: { displayName: Custom Material, tooltip: Use custom material., }, color: { displayName: Color, tooltip: Rendering color., }, }, }, Label: { properties: { __extends__: classes.cc.UIRenderer.properties, string: { displayName: string, tooltip: The label text., }, // ... }, }, }, }, };值得注意的几点每个属性条目通常携带两个字段displayName属性面板上的显示名与tooltip悬停提示。顶层classes之下以cc作为命名空间再按组件类名如Label、Sprite逐层展开这一结构与引擎 cocos/2d、cocos/ui 等模块的组件类定义一一对应。除cc外还有第三方命名空间如spSpine下的Skeleton组件其文案同样挂载在classes.sp.Skeleton下。文件头部通过/* eslint-disable quote-props */等注释关闭引号与命名风格校验因为键名大量包含非标识符字符如cc、点号路径。三、自动合并机制editor/i18n-utils.js 的实现原理README 中“编辑器自动合并”并非魔法其底层实现就位于 editor/i18n-utils.js。该文件导出两个核心函数mixin与link。3.1 mixin深合并mixin(result, ...args)将多个源对象按序深合并进result规则如下标量冲突报错当源对象中某个键在目标中已存在且值类型不可合并时会调用reportMixinFailure打印Can not mix ... into ...并给出两侧的完整路径与类型string/object/array/null便于定位冲突数组合并目标与源的同一键若都是数组则执行push(...)拼接而非覆盖对象递归普通对象则递归进入mixinObject逐层合并。3.2 link按引用路径展开继承link(root)处理各文件中出现的__extends__字段。其实现要点遍历对象树遇到__extends__: classes.cc.Animation.properties之类的字符串时按点号路径在根对象内查找目标find函数逐段in校验找不到会打印Can not find the __extends__ ...找到后先递归link目标保证其自身的__extends__也被展开再通过mixinObject把基类内容合并进当前对象对每个访问过的对象用visited集合去重防止循环引用导致死循环。这一机制让子类组件无需重复书写父类全部属性文案。典型的继承链如editor/i18n/en/animation.jsSkeletalAnimation.properties通过__extends__: classes.cc.Animation.properties继承Animation的全部属性文案editor/i18n/en/modules/ui.jsLabel、Sprite、sp.Skeleton共同继承UIRenderer.propertieseditor/i18n/en/animation.jsPoseNodeBlendTwoPose、PoseNodeFilteringBlend通过__extends__复用PoseNodeBlendTwoPoseBase.inputs的输入插槽文案。配合mixin使用时的典型调用形如link(mixin({...}, extra))即先把多个数据源合并成一张表再一次性解析所有继承引用这正是 editor/i18n/en/localization.js 与 editor/i18n/zh/localization.js 顶部module.exports link(mixin({...}))的写法。3.3 版本号注入editor/i18n/en/localization.js 还展示了另一个细节通过require(../../../package.json)读取引擎版本用pkg.version.replace(/(^\d\.\d)\..*$/, ...)截取主次版本号如3.8并拼进文档链接模板https://docs.cocos.com/creator得到help文案中的手册地址。这保证了属性面板中的帮助链接始终指向与当前引擎版本匹配的文档页。需要注意的是文档中出现的这些外部帮助链接属于引擎运行时生成的跳转数据正文引用请以仓库内 editor/i18n/zh/localization.js 源码为准。四、按 README 约定新增一个模块的国际化文件以 README 给出的“新模块xxx”为例标准步骤是在 editor/i18n/en 与 editor/i18n/zh 下各新增一个文件例如xxx.js文件内容只需module.exports { xxx: {} }编辑器加载时会自动把en与zh下的所有文件合并进ENGINE命名空间因此不要在这些文件之间互相require在xxx对象内按业务需要填充字段例如属性面板文案建议沿用classes.cc.xxx.properties的结构动画图节点可参考animation_graph与createPoseNodeOnAssetDragHandler的既有命名。仓库中已有的模块化范例editor/i18n/en/modules/ui.jsUIRenderer、Label、RichText、Sprite、UISkew以及sp.Skeleton的属性面板文案editor/i18n/en/modules/rendering.js渲染相关组件的属性文案其中MeshRenderer同样使用了__extends__继承机制见 en/modules/rendering.jseditor/i18n/zh/modules/physics.js、editor/i18n/zh/modules/terrain.js物理与地形模块的中文文案。五、文案数据在编辑器中的消费方式5.1 组件属性检查器Inspectorclasses.cc.*.properties下的displayName与tooltip会被属性面板Inspector读取并渲染。例如在 editor/i18n/en/animation.js 中cc.Animation.propertiesclips组件管理的所有剪辑、defaultClip默认播放的剪辑、playOnLoad加载后是否自动播放cc.SkeletalAnimation.propertiessockets挂点列表需先注册才能把自定义节点挂到动画骨骼上、useBakedAnimation预烘焙动画默认开启可大幅提升性能但会固定所有动画效果。这些英文文案在 editor/i18n/zh/animation.js 中有严格对应的中文译文编辑器按当前语言环境选择其一渲染。5.2 动画图Marionette / Pose Graph菜单与拖拽animation_graph与classes.cc.animation.*下的文案服务於动画状态机与姿态图编辑界面pose_graph_node_sub_categories姿态图节点创建菜单的子分类名姿态节点、混合、反向动力学、选择pose_graph_node_sub_menus子菜单项播放/采样动画剪辑、一维/二维动画混合PoseNodePlayMotion、PoseNodeSampleMotion等节点还定义了title模板如播放 {motionName}与createPoseNodeOnAssetDragHandler.displayName后者用于资源拖拽生成节点时的菜单显示文本。这一消费点有源码直接佐证editor/src/marionette/pose-graph/drag/handlers/play-motion.ts 与 sample-motion.ts 中均以i18n:ENGINE.classes.cc.animation.PoseNodePlayMotion.createPoseNodeOnAssetDragHandler.displayName的形式引用即通过i18n:ENGINE.前缀定位到EN/zh合并后数据表中的对应字段。由此可以反推 README 所述“自动合并”的实际作用范围ENGINE即合并后挂载在编辑器 i18n 命名空间上的整棵数据树。5.3 文档帮助链接helpeditor/i18n/en/localization.js 中的help.cc与help.assets为各组件与资源类型提供了指向官方手册的链接模板基于 3.8 版本号生成中文侧 editor/i18n/zh/localization.js 则指向中文手册。编辑器在属性面板的组件帮助按钮、资源类型说明等处消费这些地址。六、多语言字段编写要点总结结合仓库实际文件可提炼出以下可复用的编写准则结构即数据用嵌套对象表达层级顶层xxx为模块命名空间内部按classes/help/features等既定分类组织。features分类见 editor/i18n/zh/localization.js 起的features.categories、physics、gfx_webgl2、gpu_driven等服务于引擎功能裁剪界面描述如 “基于 Bullet 的物理系统支持”。键名保持一致同一文案的键在en与zh中必须完全一致只替换值en与zh目录树保持对称避免某一侧缺失导致回退异常。复用优先于复制子类或同类属性通过__extends__指向共享节点如classes.cc.UIRenderer.properties避免成百上千行重复文案也方便统一修改。使用displayName/tooltip约定字段属性面板条目的显示名与悬停提示分别对应这两个字段对于枚举选项可扩展tooltip_left/tooltip_right等后缀字段见 en/modules/ui.js 中 Label 对齐方式的写法。HTML 拼接提示tooltip中大量使用br换行与列表式说明可在同一字段内展示多行富文本提示。不要互相 require依赖编辑器自动合并模块文件保持彼此独立避免循环依赖与加载顺序问题——这正是 README 的核心结论。七、进阶如何在编辑器之外验证与复用验证合并逻辑mixin与link是纯函数实现见 editor/i18n-utils.js不依赖编辑器运行时可单独用 Node.js 加载require(editor/i18n-utils.js)后传入若干en/zh数据对象做合并测试冲突路径会以Can not mix ...形式打印在控制台。观察版本注入localization.js在构建时读取 package.json 的version字段生成文档链接修改主次版本号会影响帮助链接的指向。配合编辑器资源表引擎的功能裁剪项features同时出现在 editor/engine-features/schema.json、editor/engine-features/render-config.json 等配置中localization.js中的features文案即为其提供多语言标签二者需保持键名同步。结语editor/i18n/README.md虽只有寥寥数行却精准定义了 Cocos Creator 编辑器国际化资源的关键工程规范以模块文件为粒度、以自动合成为手段、以ENGINE命名空间为出口。配合 editor/i18n-utils.js 的mixin/link实现这一机制在保证 en/zh 文案零重复维护的同时支撑了属性检查器、姿态图菜单、功能裁剪面板与文档帮助链接等众多编辑场景。理解这份约定即可按同样的模式为引擎新增模块快速接入多语言文案。【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考