如何读懂 Obsidian i18n：Babel AST 字符串提取原理完整解析

如何读懂 Obsidian i18nBabel AST 字符串提取原理完整解析【免费下载链接】obsidian-i18n项目地址: https://gitcode.com/gh_mirrors/ob/obsidian-i18nObsidian i18n是一款专为 Obsidian 打造的插件国际化工具核心能力是Babel AST 字符串提取它把社区插件的main.js解析成语法树像拆积木一样精准定位所有界面文案再配合大模型批量翻译并安全写回让不懂代码的用户也能一键完成 Obsidian 插件汉化。本文用图解方式带你完整看懂这套字符串提取的工作原理。为什么不用正则而要用 AST 提取字符串最朴素的汉化方案是全文搜索替换在main.js里搜Cancel替换成取消。但这样做很容易翻车误伤代码里的同名标识符、URL 或日志常量插件更新后文本位置变化替换规则全部失效无法记录这段文字出现在哪个上下文同一句OK在不同弹窗里含义可能不同。Obsidian i18n 选择了更稳妥的路线先理解代码结构再提取字符串。Babel 是 JavaScript 生态最成熟的语法解析器它能把一整份压缩代码还原成结构清晰的抽象语法树ASTAbstract Syntax Tree。树的每个节点都带着这句话是什么类型的语法、变量叫什么、出现在哪个函数调用里等上下文信息——这正是安全提取界面文案所需的依据。 简单说正则是在找词AST 是在读懂句子结构后挑词。Babel AST 字符串提取的完整流程整个提取引擎的核心实现在 core-ast-translator.ts可以拆成四步流水线① 解析Parse代码 → 语法树引擎调用 Babel 的parse把插件main.js读成 AST。值得注意的是解析配置里开启了errorRecovery容错模式和一整套现代语法插件TypeScript、JSX、可选链等保证再怪异的压缩产物也能尽量解析成功而不是直接报错放弃。相关代码见 parseAst。② 遍历Traverse按白名单锁定UI 上下文这是提取策略的灵魂——极度保守的白名单机制。引擎不会把代码里所有字符串都抓出来只收集以下五类节点的字符串节点类型代码长相提取条件变量声明const title ...变量名在赋值白名单中赋值表达式el.textContent ...属性名在白名单中对象属性{ name: ... }键名在键名白名单中函数调用new Notice(...)函数名在函数白名单中构造表达式new Setting(...)同上默认白名单本身就是一份Obsidian UI 词典title、placeholder、textContent、setName、setDesc、Notice、renderMarkdown等等覆盖几乎所有面向用户的展示位置配置集中在 config.ts。遍历逻辑见 traverseWhitelist。③ 过滤Filter双重校验内容有效性通过白名单的字符串还要过第二道关 isValidText采用先拒绝、后放行的双重校验拒绝规则命中即丢弃URL、文件路径、十六进制颜色、CSS 单位、camelCase 变量名、纯数字、kebab-case ID……共 14 条正则定义在 AST_DEFAULT_RULES放行规则命中其一即保留包含空格多半是人类语句、包含中文等非 ASCII 字符、以标点结尾纯英文单词则作为兜底直接放行。这套设计的哲学是宁可漏提不可错提——漏掉的词条用户可以在表格里手动补而错提的词条会在应用时破坏代码。④ 指纹Fingerprint与去重每条提取结果最终被整理成一个结构简单的词条{ type: CallExpression, name: Notice, source: Saving..., target: Saving... }对应类型定义 PluginTranslationV1Ast其中typenamesource三元组构成唯一指纹用于去重和后续精准回写实现见 deduplicateResults。提取之后表格化编辑与译文回写提取出的词条进入可视化 AST 编辑器按节点类型 / 变量名 / 原文 / 译文四列展示支持行内直写、全文搜索与仅看未翻译筛选完整操作说明见官方文档 ast-editor.mdx。当你点击应用真正的回写发生。InjectorManager 会按备份 → 替换 → 健康检查三步安全执行优先从备份读取原始代码再翻译保证永远基于母语原文而非已翻译内容做二次替换调用 translate 做两级匹配先用完整指纹严格匹配匹配不到再退化为按原文宽松匹配这样即使插件版本微调、变量重命名旧译文也能继续命中替换字符串时若译文里含${变量}会先重新解析成模板字符串节点再写回见 replaceSource避免把${name}当成普通文本写坏语法。写回后系统会自动重启目标插件做健康检查一旦发现插件加载失败立刻触发自动回滚用备份恢复原始文件injector.ts。此外还有 validateSecurity 对译文做安全审计拦截eval()、script等危险模式——这套备份 回滚 审计机制就是插件汉化敢直接改写main.js的底气。如何按你的目标插件微调提取规则白名单和过滤正则都开放给用户自定义入口在插件设置的AST 配置面板i18n-ast.ts共五个可调项变量赋值白名单追加目标插件私有的变量名函数调用白名单追加自定义 UI 函数名对象键名白名单追加自定义配置项键名排除正则命中即丢弃的文本特征有效特征正则命中其一才保留的文本特征。举个例子若某插件总用showToast(...)弹提示把showToast加进函数白名单即可让 AST 提取引擎自动捕获这些文案无需改一行源码。 除了 AST 路线插件还内置了基于正则的兜底提取器 core-regex-translator.ts两者互补AST 管精准正则管覆盖。提取入口的调度逻辑位于 extract-manager.ts。总结Obsidian i18n 的 AST 提取为什么可靠把整条链路串起来看Babel AST 字符串提取的原理其实是一条层层设防的流水线Babel 容错解析把压缩代码还原成语法树UI 上下文白名单只从变量赋值、函数调用、对象键名里挑长得像界面文案的字符串拒绝/放行双重正则滤掉 URL、颜色、CSS、变量名等噪音指纹去重每条译文都有唯一坐标可追溯、可回滚备份 健康检查 自动还原让改写插件源码这件事变得可逆。正是这种保守提取 安全回写的设计Obsidian i18n 才能把原本属于程序员的黑活变成任何用户点三次按钮就能完成的插件汉化。【免费下载链接】obsidian-i18n项目地址: https://gitcode.com/gh_mirrors/ob/obsidian-i18n创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考