Ace 编辑器国际化实战指南翻译文件生成、nls 消息提取与运行时查找机制【免费下载链接】aceAce (Ajax.org Cloud9 Editor)项目地址: https://gitcode.com/gh_mirrors/ac/ace本文基于 AceAjax.org Cloud9 Editor仓库的 translations/Readme.md 展开系统讲解如何为 Ace 编辑器添加全新的语言翻译文件.json、如何通过构建脚本Makefile.dryice.js nls自动提取源码中的待翻译消息并深入解析 Ace 运行时src/lib/app_config.js的nls()翻译查找与占位符替换机制。读完本文你将掌握从“创建语言文件”到“消息被界面消费”的完整国际化工作流并能够为 Ace 自行新增一种语言支持。一、生成新翻译文件的标准流程Ace 的界面文本如自动补全弹窗提示、搜索框按钮标题、无障碍 ARIA 标签等默认以英文硬编码在源码中通过nls()调用包裹。若要提供本地化界面需要按以下三步生成并填充翻译文件原文出处translations/Readme.md第 1 步创建语言文件在仓库的translations/目录下新建一个 JSON 文件文件名为目标语言的 ID例如中文可用zh.json、法语可用fr.jsontranslations/language_id.json语言 ID 的命名完全由你决定只要不与现有文件冲突即可。当前仓库已存在的语言文件包括am.json阿姆哈拉语、es.json西班牙语、ru.json俄语、sl.json斯洛文尼亚语新增文件时同样放在该目录下。第 2 步写入$id字段在空的 JSON 文件中写入语言 ID 标识{ $id: language_id }例如为俄语文件写入的就是{$id: ru}见 translations/ru.json。这个$id字段至关重要运行时定位到某份翻译消息表后会读取其$id用于调试告警信息详见下文“运行时查找机制”。第 3 步运行 nls 提取命令在仓库根目录执行node Makefile.dryice.js nls该命令会自动扫描src/下的源码提取所有nls(key, defaultString)调用完成两件事同步默认英文消息表把源码中新出现的、尚未登记的消息写入 src/lib/default_english_messages.js补齐所有翻译文件把默认消息表中每个 key 都合并进translations/下每个.json翻译文件缺失的翻译统一填充为空字符串供翻译者逐条填写。命令执行后控制台会输出Saved 文件名之类的提示对应实现见 Makefile.dryice.js 的extractNls()函数。二、extractNls() 到底做了什么源码级拆解node Makefile.dryice.js nls入口在 Makefile.dryice.js命中type nls后调用extractNls()。其完整逻辑Makefile.dryice.js可拆解为以下步骤加载默认消息表require(./src/lib/default_english_messages).defaultEnglishMessages得到当前默认英文消息的键值集合。递归扫描src/目录跳过包含_test的测试文件用正则匹配所有形如nls(key, defaultString)或nls(key, defaultString)的调用/nls\s*\(\s*(([^\\]|\\.)|([^\\]|\\.)),\s*(([^\\]|\\.)|([^\\]|\\.))/g该正则要求nls的第一个参数key和第二个参数默认英文串都是字符串字面量因此只有“硬编码字符串常量”形式的消息才会被提取动态拼接的字符串无法被识别。合并新 key若某 key 尚不存在于默认消息表则以defaultData[key] defaultString的形式追加。回写默认消息文件将更新后的默认消息表重新序列化写入 src/lib/default_english_messages.js保持英文基准与源码同步。补齐各翻译文件遍历translations/下所有.json文件将默认表中的每个 key 都写入其中existing[i] existing[i] || ——已有翻译保留原值缺失翻译补空字符串从而保证所有语言文件始终拥有与默认表一致的完整 key 集合。这也是为什么步骤 2 只需写{$id: ...}一行剩下的全部 key 会由extractNls()自动生成。执行完后打开新语言文件你会看到类似 translations/ru.json 的结构——数十个 key 全部就位翻译值待填。三、翻译文件的结构与完整 key 清单以 translations/ru.json 为参照Ace 当前的全部可翻译消息分为以下几类对应 key 前缀分类前缀覆盖的界面区域自动补全autocomplete.补全弹窗的 ARIA 标签、加载提示编辑器editor.编辑区滚动容器与槽gutter的无障碍描述搜索框search-box.查找/替换输入框占位符、按钮标题、计数器提示/命令面板prompt.最近使用、其他命令、无匹配命令文本输入text-input.光标位置 ARIA 标签代码折叠gutter.code-folding.折叠/展开按钮的标题与 ARIA 标签行号槽标注gutter.annotation./gutter-tooltip.错误/警告/信息/安全/建议标注的无障碍描述错误标记error-marker.错误状态提示其他inline-fold.、editor.tooltip.行内折叠、禁用编辑提示这些消息在源码中的实际消费点包括均为nls()调用处自动补全弹窗 ARIAsrc/autocomplete/popup.js搜索框全部按钮与占位符src/ext/searchbox.js编辑器滚动区与槽的无障碍属性src/editor.js行号槽折叠控件与标注src/layer/gutter.js光标位置提示src/keyboard/textinput.js翻译时需注意翻译值必须完整保留占位符如$0、$1、{n}仅翻译自然语言部分。以默认消息search-box.search-counter: $0 of $1为例俄语翻译为$0 из $1见 translations/ru.json$0/$1被原样保留运行时由nls()填入实际数字。四、运行时如何消费翻译nls() 查找与占位符替换翻译文件生成后并不会被自动加载还需要在应用中通过config.setMessages()注入随后界面代码的nls()调用才会返回对应语言的文本。4.1 消息注入与查找逻辑config.setMessages(value, options)src/lib/app_config.js用于设置当前使用的消息表可选options.placeholders指定占位符风格dollarSigns或curlyBrackets。config.nls(key, defaultString, params)src/lib/app_config.js的查找优先级为messages[key]按 key 精确命中翻译messages[defaultString]key 未命中时尝试用默认英文串本身作为 key 查找允许“翻译了默认串但 key 不同”的情况defaultString以上都未命中时回退到源码中的默认英文文本。未命中时还会输出告警提示在messages.$id对应的语言表中找不到某 key——这正是$id字段在运行时的用途。相关告警实现见 src/lib/app_config.js。4.2 占位符替换当传入params时nls()支持两种占位符风格美元符风格默认$0、$1… 对应params[0]、params[1]…$$转义为字面$花括号风格{0}、{1}… 对应params[0]、params[1]…。默认消息表 src/lib/default_english_messages.js 中的字符串如text-input.aria-label: Cursor at row $0即采用美元符风格。替换逻辑见 src/lib/app_config.js。4.3 测试用例验证仓库的 src/config_test.js 给出了完整的nls行为测试可作为理解与排错参考nls(untranslated_key,bar $1)未命中任何翻译时返回默认串bar $1key 未命中但默认串被翻译时返回翻译结果nls(test_key, this text should not appear)命中test_key时返回翻译值而非默认串setMessages({...}, {placeholders: curlyBrackets})与{placeholders: dollarSigns}下同一字符串的$n/{n}替换结果不同测试注释明确“默认使用美元符”。五、从零新增一种语言的完整清单综合以上内容为 Ace 新增一种语言的完整步骤如下在 translations/ 目录创建language_id.json写入{$id: language_id}在仓库根目录运行node Makefile.dryice.js nls生成带全部 key值为空串的翻译骨架打开生成的文件逐条将英文翻译为目标语言保留$0/$1/{n}等占位符在应用初始化时通过config.setMessages(require(.../language_id.json))注入消息表若使用打包构建还需将翻译文件纳入构建产物验证对照 src/config_test.js 的用例逻辑确认占位符替换与回退行为符合预期。六、注意事项与限制仅提取字符串常量extractNls()的正则只匹配nls(key, default)字面量形式动态 key 不会被自动提取key 集合始终对齐每次执行node Makefile.dryice.js nls都会把默认表中的新 key 合并进所有语言文件因此建议在源码新增nls()消息后重新运行该命令避免翻译文件缺 key未翻译的 key 回退英文翻译值为空串或缺失时nls()依次回退到默认串翻译、默认英文串界面不会因此报错占位符风格统一翻译文件中$n与{n}混用可能导致替换行为不一致建议跟随默认表统一使用$n风格或在setMessages时显式指定placeholders。参考资料仓库内路径官方翻译流程文档translations/Readme.mdnls 提取构建脚本Makefile.dryice.js、命令分发入口 Makefile.dryice.js默认英文消息表src/lib/default_english_messages.js运行时 nls 实现src/lib/app_config.js现有翻译示例translations/ru.jsonnls 行为测试src/config_test.js【免费下载链接】aceAce (Ajax.org Cloud9 Editor)项目地址: https://gitcode.com/gh_mirrors/ac/ace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考