GrapesJS I18n 国际化模块完全指南配置、API 与多语言插件开发【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjsGrapesJS 内置的I18n 模块负责编辑器界面所有字符串的国际化和动态更新允许开发者在不改源码的情况下替换任意 UI 文案、接入新的语言甚至为自定义插件提供一套完整的本地化结构。本文以 I18n API 文档 与 I18n 模块指南 为核心骨架结合packages/core下的模块源码与测试用例系统讲解初始化配置、核心 API、事件机制、字符串更新方法与插件本地化最佳实践读完即可为你的 GrapesJS 实例接入多语言或深度定制界面文案。模块概述与使用入口I18n 模块I18nModule位于 模块实现负责管理编辑器的语言环境locale与翻译消息集messages底层依赖underscore的deepMerge与isUndefined等工具并继承自Module抽象基类。使用该模块有两条路径初始化时传入配置在grapesjs.init()中通过i18n配置对象定制模块初始状态实例化后调用 API通过editor.I18n获取模块实例后动态调用其方法。const editor grapesjs.init({ i18n: { locale: en, localeFallback: en, messages: { it: { hello: Ciao, /* ... */ }, // ... }, }, }); // 编辑器实例化之后通过该入口使用模块 API const i18n editor.I18n;初始化配置六大配置项与默认值I18n 的配置对象定义在 config.ts类型为I18nConfig。所有配置项及其默认值如下配置项类型默认值说明localestringen当前使用的语言环境值localeFallbackstringen回退语言环境当目标语言缺失某条消息时使用detectLocalebooleantrue是否通过浏览器语言自动检测语言环境debugbooleanfalse在 i18n 资源缺失时是否输出警告日志messagesRecordstring, any{ en: {...} }翻译消息集按语言代码组织messagesAddRecordstring, anyundefined附加消息用于直接从配置中扩展默认messages集合其中messages默认值由config()工厂函数注入内置的英文语言文件messages: { en }en即 英文语言文件 导出的对象。语言代码遵循ISO 639-1标准如en、it、zh、fr。语言检测的底层实现detectLocale默认开启其逻辑体现在模块构造函数中if (this.config.detectLocale) { this.config.locale this._localLang(); }_localLang()见 index.ts读取window.navigator.language || window.navigator.userLanguage并取-分割后的第一部分即navigator.language it-IT时得到it取不到时兜底为en_localLang() { const nav (hasWin() window.navigator) || {}; const lang nav.language || nav.userLanguage; return lang ? lang.split(-)[0] : en; }因此默认情况下编辑器会跟随浏览器语言自动切换若你希望固定语言需显式设置locale并关闭detectLocale: false这一点在测试用例Init with config中也有验证见 I18n 测试用例。导入第三方语言文件GrapesJS 核心默认只内置英文其他语言需要手动导入。语言文件可以从grapesjs/locale/*路径引入packages/core/package.json中files字段已包含locale目录exports的./*: ./*允许按子路径引用import grapesjs from grapesjs; import it from grapesjs/locale/it; import tr from grapesjs/locale/tr; const editor grapesjs.init({ // ... i18n: { // locale: en, // 默认语言 // detectLocale: true, // 默认开启自动检测浏览器语言 // localeFallback: en,// 默认回退语言 messages: { it, tr }, }, });配置完成后对于默认语言为意大利语的浏览器编辑器会自动以意大利语渲染detectLocale默认开启。仓库内置的语言文件位于 locale 目录包含en、it、zh、fr、de、es、ru、ar、tr、vi、ko、pt等二十余种语言可作为对照参考。核心 API 详解模块实例editor.I18n暴露以下方法完整签名与示例见 I18n API 文档。setLocale(locale)切换当前语言i18n.setLocale(it); // 返回 this支持链式调用源码实现index.ts在更新config.locale之前先触发i18n:locale事件并携带新旧语言值setLocale(locale: string) { const { em, config, events } this; em.trigger(events.locale, { value: locale, valuePrev: config.locale }); config.locale locale; return this; }getLocale()获取当前语言const current i18n.getLocale(); // - it直接返回this.config.locale。getMessages(lang?, opts?)获取全部或指定语言的消息i18n.getMessages(); // - { en: { hello: ... }, ... } i18n.getMessages(en); // - { hello: ... }lang可选指定要返回的语言不传返回整个语言集合。opts.debug可选为true时若指定语言不存在会打印警告。源码在指定lang且消息集中不存在该语言时调用_debug输出lang i18n lang not foundindex.ts。setMessages(msg)整体替换消息集i18n.getMessages(); // - { en: { msg1: Msg 1, msg2: Msg 2, } } i18n.setMessages({ en: { msg2: Msg 2 up, msg3: Msg 3, } }); // 消息集被整体替换 i18n.getMessages(); // - { en: { msg2: Msg 2 up, msg3: Msg 3, } }注意setMessages是直接替换config.messages见 index.ts而非合并因此msg1会消失同时触发i18n:update事件。测试用例setMessages method验证了这种整体替换语义。addMessages(msg)增量更新消息集i18n.getMessages(); // - { en: { msg1: Msg 1, msg2: Msg 2, } } i18n.addMessages({ en: { msg2: Msg 2 up, msg3: Msg 3, } }); // 消息集被更新深合并 i18n.getMessages(); // - { en: { msg1: Msg 1, msg2: Msg 2 up, msg3: Msg 3, } }与setMessages不同addMessages通过deepMerge与现有消息深合并index.ts先触发i18n:add事件再调用setMessages完成合并因此也会触发i18n:update。测试用例addMessages with deep extend possibility验证了多层级对象的深度合并行为合并时同名字符串会被覆盖而对象会逐层合并保留未冲突的键。t(key, opts?)翻译消息核心方法obj.setMessages({ en: { msg: Msg, msg2: Msg {test} }, it: { msg2: Msg {test} it }, }); obj.t(msg); // - Msg obj.t(msg2, { params: { test: hello } }); // 使用参数 // - Msg hello obj.t(msg2, { l: it, params: { test: hello } }); // 指定语言 // - Msg hello itt的参数与行为key要翻译的键名支持点号路径访问嵌套消息如key1.key2.msg2测试用例Translate method with object structure已验证opts.params占位符参数对象模板中用{paramName}表示替换后结果会被trim()opts.l指定翻译语言不传则使用当前 localeopts.lFlb指定回退语言不传则使用config.localeFallbackopts.debug资源缺失时是否输出警告。翻译流程index.ts为先在当前语言查找未命中则回退到localeFallback语言查找仍为空时按debug配置输出key i18n key not found in locale lang警告。_getMsg内部实现嵌套取值逻辑if (!result key.indexOf(.) 0) { result key.split(.).reduce((lang, key) { if (isUndefined(lang)) return; return lang[key]; }, msgSet); }占位符替换由_addParams完成使用正则{([\w\d-]*)}全局匹配_addParams(str: string, params: Recordstring, any) { const reg new RegExp({([\\w\\d-]*)}, g); return str.replace(reg, (m, val) params[val] || ).trim(); }getConfig()获取配置对象const config i18n.getConfig();直接返回模块的配置对象包含locale、localeFallback、detectLocale、debug、messages等当前生效值。事件机制I18n 模块在 types.ts 中通过枚举定义了三个事件均通过editor.on(...)订阅事件触发时机回调参数i18n:add调用addMessages时(messages)新增的消息集i18n:update调用setMessages含addMessages内部合并时(messages)更新后的消息集i18n:locale调用setLocale时({ value, valuePrev })新语言值与旧语言值editor.on(i18n:add, (messages) { /* ... */ }); editor.on(i18n:update, (messages) { /* ... */ }); editor.on(i18n:locale, ({ value, valuePrev }) { /* ... */ });测试用例i18n events测试文件验证了一次addMessages会触发 1 次i18n:add与 1 次i18n:update一次setLocale触发 1 次i18n:locale。注意i18n:locale事件在config.locale更新之前触发回调中的valuePrev即旧语言值。典型应用场景切换语言后同步刷新相关面板文案、或把用户语言偏好持久化到后端。实战更新默认 UI 字符串定位字符串路径GrapesJS 的默认字符串都定义在 英文语言文件 中按模块分门别类组织。例如 Style Manager 的空状态提示{ // ... styleManager: { empty: Select an element before using Style Manager, // ... }, // ... }要修改某个字符串只需沿着其在语言文件中的嵌套路径用addMessages覆盖对应键即可。例如将空状态提示改为自定义文案editor.I18n.addMessages({ en: { // 与语言文件中的嵌套结构保持一致 styleManager: { empty: New empty state message, }, }, });由于addMessages是深合并这种局部覆盖不会影响styleManager下的其他键。推荐做法封装进插件虽然直接调用 API 就能生效官方指南强烈建议把这类 API 调用封装进插件保证初始化顺序与可复用性const myPlugin (editor) { editor.I18n.addMessages({ /* ... */ }); // ... }; grapesjs.init({ // ... plugins: [myPlugin], });插件的加载机制详见 Plugins 模块指南。覆盖自动生成的字符串并非所有 UI 字符串都写在语言文件中——部分标签是从组件的id、name等属性自动生成的。以 Style Manager 为例语言文件中styleManager.properties是一个默认几乎为空的对象// ... styleManager: { // ... properties: { // float: Float, }, // ... }, // ...该对象用于翻译 Style Manager 中的属性名。属性标签的默认生成规则是直接从属性名生成例如font-size会被渲染为Font sizeproperties对象则用于覆盖这些自动生成的名称。若你希望把margin系列属性的名称改为Top/Right/Left/Bottom做法如下editor.I18n.addMessages({ en: { styleManager: { properties: { // 键为属性名或属性 id margin-top: Top, margin-right: Right, margin-left: Left, margin-bottom: Bottom, }, }, }, });同样的机制也适用于 Trait Manager语言文件中traitManager.traits.labels用于翻译 trait 名称traitManager.traits.attributes用于翻译输入属性如placeholdertraitManager.traits.options用于翻译下拉选项如target的_blank显示为New window详见 英文语言文件。实战插件开发中的本地化如果你的插件需要支持多语言或定制默认文案官方推荐以下目录结构详见 I18n 模块指南plugin-dir |- package.json |- README.md |- ... |- src |- index.js |- locale // 在 src 下创建 locale 目录 |- en.js // 所有默认字符串放在这里插件专属字符串放在插件名命名的键下避免与核心字符串或其他插件冲突// src/locale/en.js export default { grapesjs-plugin-name: { yourKey: Your value, }, };插件入口文件引入en.js并暴露i18n选项以便用户传入其他语言文件// src/index.js import en from locale/en; export default (editor, opts {}) { const options { i18n: {}, // ... ...opts, }; // ... editor.I18n.addMessages({ en, ...options.i18n, }); };构建时将 locale 文件编译输出到rootDir/locale目录使其对插件用户可直接引用该目录可加入 git 忽略但必须发布到 npm registry。最终插件用户即可这样使用多语言import grapesjs from grapesjs; // 从你的插件导入 import yourPlugin from grapesjs-your-plugin; import ch from grapesjs-your-plugin/locale/ch; import fr from grapesjs-your-plugin/locale/fr; const editor grapesjs.init({ // ... plugins: [yourPlugin], pluginsOpts: { [yourPlugin]: { i18n: { ch, fr }, }, }, });值得一提的是使用本仓库的 grapesjs-cli 工具packages/clibuild命令通过--localePath指定 locale 目录见 core 构建脚本初始化插件项目时会默认自动创建上述 locale 目录与文件结构init命令默认开启该选项即便当前不需要 i18n 也建议保留便于后续扩展。为仓库贡献新语言GrapesJS 官方欢迎社区贡献新语言的翻译模块在较新版本加入中文社区也有对应的 中文语言文件 作为参考。贡献流程大致如下先检查 locale 目录 中是否已存在目标语言文件避免重复工作在仓库中开启一个 issue 声明要翻译的语言避免与其他贡献者冲突从dev分支新建开发分支在同一目录下复制 英文语言文件 并重命名为目标语言代码遵循 ISO 639-1 标准逐条翻译字符串部分键如styleManager.properties未在文件中显式列出可参考其他语言文件补全翻译完成后向dev分支提交 Pull Request并在 PR 描述中引用 issue如Closes #1234以便合并时自动关闭。小结与注意事项默认英文、按需导入核心只内置en其余语言从grapesjs/locale/*手动导入后经messages配置注入。detectLocale默认开启编辑器会跟随浏览器语言需要固定语言时记得显式设置locale并关闭检测。setMessages与addMessages语义不同前者整体替换后者深合并日常覆盖单个字符串应使用addMessages。模板占位符消息中可用{param}占位翻译时通过t(key, { params })注入t支持点号路径与自定义l/lFlb语言参数。自动生成字符串属性类标签默认由名称生成通过styleManager.properties等路径覆盖。插件本地化遵循插件名键 locale 目录 暴露i18n选项的结构即可让插件用户无缝接入多语言。调试辅助开启debug: true或调用t/getMessages时传opts.debug可在消息缺失时通过em.logWarning获得警告帮助快速定位漏译的键。结合 API 文档、模块指南、模块实现源码 与 测试用例你可以在任何基于 GrapesJS 的项目中快速落地完整的国际化方案。【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考