FigmaCN翻译引擎深度解析：MutationObserver + TreeWalker实时翻译DOM的完整机制

FigmaCN翻译引擎深度解析MutationObserver TreeWalker实时翻译DOM的完整机制【免费下载链接】figmaCN中文 Figma 插件设计师人工翻译校验项目地址: https://gitcode.com/gh_mirrors/fi/figmaCNFigmaCN 是一款 Figma 中文插件Figma 汉化插件它用 MutationObserver TreeWalker 实时翻译 Figma 网页的 DOM 节点把界面菜单、属性面板、提示文案统统变成中文。本文带你完整看懂这套 Figma 翻译引擎的运作机制——即使不精通前端也能明白它是怎么做到打开即中文、操作不丢字的。项目说明当前版本1.8.0见 manifest.json翻译词典translations.json4300 条人工翻译、设计师校验过的词条核心引擎content.js自动注入*.figma.com的所有页面与 iframe 30 秒看懂FigmaCN 翻译引擎的运行流程Figma 页面加载document_end │ ├─ ① fetch 词典 translations.json ├─ ② 构建 dataMap / reverseDataMap / patternEntries ├─ ③ TreeWalker 全量扫描 document.body首屏翻译 │ └─ ④ MutationObserver 持续监听 ├─ 新增节点 → 局部 TreeWalker 子树扫描 ├─ 文本变化 → 单节点翻译 └─ 属性变化 → 属性翻译一句话总结先翻存量再听增量。首屏由 TreeWalker 一次性扫完之后切换面板、打开菜单、弹出提示时新出现的文字都会被 MutationObserver 捕获并即时翻译——这就是实时二字的来源。 第 1 步加载 4000 条翻译词典content.js 启动时先用fetch拉取 translations.json。词典是一个英文 → 中文的二维数组示例[ [Zoom to fit, 缩放以适应大小], [Youre about to move the file {} to trash., 您即将把文件 {1} 移到回收站。] ]加载完成后引擎把词典拆成 3 份结构content.js#L32-L52结构作用dataMap精确匹配主表英文原文 → 中文译文reverseDataMap反向表中文 → 英文用于后文的译文还原patternEntries含{}通配符的模式词条会被转换成正则捕获组{}是万能占位符一条词条即可覆盖带动态内容的文案比如任意文件名而{1}、{2}编号占位符还支持语序调整——英文的 move the file A to trash 能自然译成中文语序的把文件 A 移到回收站。 第 2 步TreeWalker 全量扫描首屏页面加载完成后translateSubtree() 用document.createTreeWalker从document.body开始逐节点遍历配合NodeFilter做精准过滤文本节点→ 接受翻译textContentFigma 自定义i18n-text元素→ 接受交给专门的translateI18nText()处理带目标属性的元素data-label、placeholder、data-tooltip等 5 个属性见 content.js#L59→ 接受翻译属性值其他节点→ 跳过FILTER_SKIP遇到禁止区则整棵子树直接拒绝FILTER_REJECT扫描完 body 后还会用querySelectorAll(i18n-text)再兜底扫一遍content.js#L406-L407。至此首屏翻译完成。 第 3 步MutationObserver 接管实时翻译首屏之后Figma 是一个活的单页应用切面板、开菜单、弹 Toast 都在不停改写 DOM。FigmaCN 用一个单一合并观察者content.js#L364-L401监听document.body配置只有 4 项content.js#L24-L29配置项值监听什么childListtrue节点增删新面板、新菜单subtreetrue整个子树而不只是直接子级attributeFilter5 个属性只盯翻译相关的属性变化characterDatatrue文本内容本身的修改观察者回调按 3 种变化分流处理childList新增节点文本节点直接翻译元素节点则触发一次局部 TreeWalker 子树扫描覆盖其内部的文本、属性与i18n-textattributes属性变化只处理 5 个目标属性逐个translateAttribute()characterData文本变化单节点翻译i18n-text走专门通道为什么不用setInterval轮询轮询是定时瞎扫MutationObserver 是有变化才通知开销更低、延迟更小而且只有译文 ≠ 原文时才写回 DOM天然避免自我触发的死循环。 防误伤清单这些区域 FigmaCN 绝不翻译实时的另一面是克制。以下区域会被shouldSkipTranslation()content.js#L130-L146识别并跳过区域判断方式为什么跳过代码 / 插件编辑器translateno 编辑器特征PRE/CODE/monaco/codemirror避免export、const等代码关键字被翻译变量名面板祖先节点含variable_name--root类名用户自定义的变量名不能动正在编辑的富文本contenteditabletrue输入区评论、标注正在打字替换会打断输入i18n-text内部文本父级是 Figma 自定义元素交给整句翻译避免中英文混排性能细节skipRootCache会缓存最近判定为跳过区的根节点其子树再有变化时直接跳过省去反复向上查找父级的开销content.js#L61-L62。还有一个巧思是译文还原i18n-text里可能嵌着子元素FigmaCN 先把子元素译成中文再用reverseDataMap把中文还原成英文原文去匹配整句词条命中后重建文本片段——保证整句译文完整、子元素不丢失content.js#L238-L254。⏱️ 完整时序从打开 Figma 到看到中文浏览器在*.figma.com页面document_end时机注入 content.jsall_frames: true保证 iframe 同样生效manifest.json#L13-L24fetch词典文件通过web_accessible_resources对 Figma 页面暴露见 manifest.json#L28-L33构建 3 份匹配结构TreeWalker 全量扫描 body → 首屏变中文observer.observe(document.body)→ 此后一切 DOM 变化实时翻译background.js 只在首次安装时打开项目主页更新时不弹页面打扰用户️ 三种安装方式体验同一个翻译引擎方式适合谁特点Chrome / Edge / Firefox 商店版普通用户一键安装刷新 Figma 页面即生效油猴脚本版脚本玩家scripts/figmaCN.user.js 远程拉取 master 最新代码跟随仓库自动更新手动加载已解压扩展开发者在扩展管理页开启开发者模式选择解压后的插件文件夹详细的逐步安装说明见 README.md。 想看懂源码克隆仓库动手看看git clone https://gitcode.com/gh_mirrors/fi/figmaCN推荐阅读顺序src/manifest.json —— 插件如何被注入 Figma 页面src/js/content.js —— 翻译引擎的全部逻辑400 行出头src/js/translations.json —— 4300 条人工翻译词条scripts/figmaCN.user.js —— 油猴版如何远程复用同一套引擎一个内容脚本 一份词典就能让 Figma 全程说中文——这就是 FigmaCN 翻译引擎的完整机制。【免费下载链接】figmaCN中文 Figma 插件设计师人工翻译校验项目地址: https://gitcode.com/gh_mirrors/fi/figmaCN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考