MongoDB Compass隔离版汉化：asar解包与语言包补丁

1. 先搞清楚这个版本"隔离"了什么，别上来就拆包

MongoDB Compass Isolated Edition 的汉化，本质上不是"装个语言包"那么简单。Compass 这套工具用的是 Electron 壳加 React 前端，界面文案全部打包在resources/app.asar这个归档文件里，Isolated Edition 为了适配完全离线、内网封闭的使用环境，在构建阶段就把一部分会主动往外发请求的模块裁掉了——自动更新通道、使用统计上报、部分在线文档的跳转入口、依赖外部瓦片服务的地理可视化面板，这些在隔离版里要么不存在，要么被改成静默失败。所以很多人第一次接触这个版本会觉得"菜单比别人少一截"，其实不是坏了，是设计如此。

汉化这件事跟"隔离"属性并不冲突。隔离是编译期决定的模块裁剪，属于代码层面的取舍；汉化改的是界面展示层的字符串资源，两者在不同的层面上。我见过有人担心改了资源文件会破坏隔离特性，这个顾虑可以放下，只要你不去动网络请求相关的逻辑分支，不把被裁掉的模块手动补回去，汉化不会影响它在离线环境里的稳定性。真正需要担心的是另一件事：Isolated Edition 的安装包完整性校验比社区版更严格，直接改 asar 有可能让程序起不来，这个后面会详细讲怎么绕。

写这篇东西的出发点很实际：手上有一批内网机器，跑的就是这个隔离版，用的人不都熟悉英文界面，尤其是刚接触文档型数据库的同事，看到 Collection、Aggregation Pipeline、Schema Analyzer 这些词就发怵。我前后折腾了几轮，从最早的暴力替换字符串，到后来的语言包补丁加脚本化流程，踩过的坑基本都在这了。适合谁看：需要在离线环境里维护这套工具的人、想做内部工具本地化的人、以及单纯好奇 Electron 应用怎么改文案的人。不需要你懂 React，但基本的命令行操作和 JSON 语法得会。

1.1 隔离版和普通版在文件结构上的真实差异

先说结论：目录骨架几乎一样，差别在细节。两个版本都是典型的 Electron 打包结构，安装根目录下有一个可执行文件，旁边是resources文件夹，里面躺着app.asar、可能存在的app.asar.unpacked、以及locales（这个是 Chromium 自己的多语言资源，管的是右键菜单、拼写检查这类浏览器级文案，跟 Compass 界面无关，别搞混）。隔离版在resources里通常还会多一个配置文件或者构建标记，用来在运行时判断是否需要屏蔽某些功能入口。

真正的差异体现在app.asar内部。普通版里能看到完整的更新检查模块、遥测上报模块，隔离版这两个目录通常被删掉或者替换成空实现。这意味着如果你拿普通版的汉化补丁直接往隔离版上套，打包过程大概率会报"文件不存在"，因为补丁脚本里可能引用了被裁掉的路径。我的做法是：永远以隔离版自己的解包结果为准，先解包、再比对、再生成补丁，不要跨版本复用。

还有一个容易忽略的点是版本号的位置。Compass 的版本信息写在package.json里，同时也硬编码在"关于"对话框的组件里。汉化的时候如果你顺手把版本号也改了，后面排查问题时会对不上号，跟同事沟通"你装的是哪个版本"会变成一场灾难。建议在开始动手前，把版本号、构建号、安装日期截图存一份，写进你的变更记录里。

1.2 动手前必须确认的三件事

第一件，确认安装路径可写。Windows 上如果装在Program Files下，默认权限是不允许普通用户修改文件的，你得用管理员权限打开编辑器，或者干脆把整个安装目录复制一份到用户目录下做实验。macOS 上应用在/Applications里，改之前先确认自己有写权限，同时注意系统对应用包做的隔离标记，改完之后可能需要重新处理一次。

第二件，确认有没有可用的语言切换入口。Compass 内置了国际化框架，部分版本在偏好设置里能选语言，但语言列表里未必有中文，或者有中文但翻译覆盖率很低。这时候汉化的正确姿势不是"新造一套机制"，而是"往已有的机制里补内容"——把中文语言包补齐，再让程序加载它。如果设置里压根没有语言选项，那就得走强制指定语言的路子，改的是启动参数或者初始化代码里的默认值。

第三件，确认能不能接受"改完要重新走一遍"的维护成本。Compass 更新频率不低，每次升级都会把app.asar整个替换掉，你改的东西全部归零。所以动手前先想清楚：这是一次性折腾，还是要长期维护？如果是要长期维护，那就必须走脚本化路线，把手动步骤固化成可重复执行的流程，否则每次升级都是一次折磨。我自己第一版是手动改的，第二次升级之后花了半小时才想起来当初改了哪些文件，从那以后就老老实实写脚本了。

1.3 三条技术路线，选哪条取决于你的耐心

第一条路线看起来最优雅，但它成立的前提是语言资源文件独立放在 asar 外部。我试过几个版本，有的版本确实把locales目录放在resources下面，但那是 Chromium 的界面语言，不是 Compass 的业务文案。第二条路线是主流选择，也是这篇要重点讲的。第三条路线我不推荐绝大多数人尝试，隔离版的构建参数跟公开版本不完全一致，你费劲编译出来的东西可能跟官方分发的行为对不上，出了问题很难判断是构建引入的还是原本就有。

2. 拆包前的准备：备份、工具链和版本锁定

准备工作做扎实，后面能省掉一半的返工。我现在的习惯是：拿到一台新机器，先不动手改，先做三件事——完整备份、记录指纹、跑通一次原版启动。备份是把整个安装目录复制一份到别处，别嫌占空间，出问题时这是唯一的救命稻草。记录指纹是指对app.asar算一次哈希，记下大小和修改时间，将来对比改动有没有生效、有没有被升级覆盖，一眼就能看出来。跑通原版启动是确认环境本身没问题，避免改完之后发现连不上数据库，结果折腾半天才意识到是网络策略的问题。

工具链方面，核心就一个：能操作 asar 归档的工具。官方提供的 Node 包用起来最稳，命令行调用一次就能解包和打包。另外准备一个像样的文本编辑器，支持大文件搜索和批量替换的那种，app.asar解出来之后是几千个文件、几十兆的 JS，用系统自带记事本打开等于自虐。最后准备一个 diff 工具，用来对比改动前后的差异，尤其是当你改了几十个文件之后，靠肉眼是看不出哪里改坏的。

2.1 定位关键目录，别在错误的地方浪费时间

不同系统下的路径差异不小，我把常见位置整理了一下：

• Windows：安装目录下resources\app.asar，用户级安装通常在用户目录的AppData\Local下的程序目录里
• macOS：应用包右键"显示包内容"，进入Contents/Resources/
• Linux：常见在/opt或/usr/lib下的应用目录里，resources/app.asar

进去之后先看清楚有哪些东西。app.asar是主体，app.asar.unpacked是打包时特意留在外部的原生模块或者大文件，这两个要一起处理，只动其中一个打包出来会缺文件。locales目录基本可以忽略，那是 Chromium 的。如果有app文件夹而不是app.asar，恭喜你，说明这个版本本来就是目录形式分发，直接改目录就行，省掉打包环节。

注意：app.asar.unpacked里的内容是原样引用的，重新打包app.asar时不要把它塞回去，否则原生模块的路径会错乱，表现是启动时报模块加载失败。

2.2 把 asar 工具装好，顺便验证一下版本

Node 环境准备好之后，装官方那个 asar 工具就行。我不建议全局安装，用 npx 调用更干净，也避免不同项目之间的版本冲突。

node -v npx @electron/asar --version

第一行确认 Node 版本别太老，第二行确认工具能跑起来。如果网络受限装不上，那就得提前在有网的环境里把包下载好再拷过去，这个在隔离环境里是常态，别等到现场才发现装不了。

解包命令很直接：

npx @electron/asar extract app.asar app_src

解出来之后检查目录结构，正常应该能看到package.json、主进程入口文件、渲染进程的静态资源目录。如果解出来只有一个几兆的空壳，说明命令用错了或者文件本身就是坏的，重新来一遍。

2.3 建立一套可回滚的备份规范

我现在的备份分三层，听着麻烦但真出事的时候很省心。

第一层是原始安装目录的整体副本，命名带日期和版本号，比如compass-isolated-1.x-backup-20240115，这个副本永远不动，只用来回滚。第二层是app.asar单文件的副本，改之前拷一份出来，出问题时直接替换回去，比重新安装快得多。第三层是语言包的版本管理，所有翻译文件放在一个独立目录里，用 git 或者简单的目录快照管理，每次改完提交一次，能清楚看到哪个词条什么时候改的。

顺便记一份校验清单，把关键文件的哈希值记下来：

# macOS / Linux shasum -a 256 app.asar # Windows PowerShell Get-FileHash app.asar -Algorithm SHA256

这份清单有两个用途：确认自己打包出来的文件确实是新的，以及每次程序升级后对比一下，快速判断哪些文件被替换了，从而知道自己的补丁还有没有效。

3. 汉化的核心实现：从资源定位到重新打包

真正开始改的时候，最耗时间的不是翻译，是找文案放在哪。Compass 的界面文案分散在两个地方：一部分在主进程和渲染进程的 JS 里直接写着，另一部分走国际化框架的键值映射。前者是硬编码，得逐个文件搜；后者集中在一个或几个 JSON 文件里，改起来痛快。我的一般流程是先用界面上的典型词去搜，判断它属于哪一类，再决定后续策略。

搜索的技巧在于选对关键词。别搜"Connect"这种到处都是的词，搜按钮上的完整短语，或者带上下文的组合，比如界面上显示"Create Database"，就搜这个完整字符串，命中率会高很多。命令大致这样：

grep -rn "Create Database" app_src/ --include="*.js" --include="*.json" | head -20

如果命中的是某个 JSON 文件里的键值对，那说明走的是国际化路线，皆大欢喜；如果命中的是 JS 里的字符串字面量，那就得看看上下文，判断这个字符串是纯展示还是有逻辑用途。

3.1 语言包的结构长什么样，键名怎么理解

国际化框架的常见做法是拿英文原文当键名，值就是翻译。这种设计对汉化特别友好，因为键名本身就是上下文，不需要额外查对照表。

{ "Connect": "连接", "Disconnect": "断开连接", "Create Database": "新建数据库", "Drop Collection": "删除集合", "Documents": "文档", "Aggregations": "聚合", "Schema": "模式", "Indexes": "索引", "Explain Plan": "执行计划" }

上面这是示意结构，实际文件里通常是嵌套的，按模块分组，层级可能有三四层。改的时候要注意几个细节。占位符不能动，形如{{count}}或者%s的部分是运行时替换的，翻译的时候位置可以调整，但符号本身必须原样保留，否则会显示成空白或者直接报错。复数形式要注意，英文用_one、_other这种后缀区分单复数，中文没有这个概念，但键名得保留，值可以写成一样的。带 HTML 标签的文案要小心，标签是渲染用的，翻译时标签位置可以挪，但不能删。

还有一类特殊情况：有些文案是拼接出来的，比如"共 3 个文档"这种，英文可能是{{count}} documents found，中文习惯是"找到 {{count}} 个文档"。这种调整语序没问题，但要确认替换变量的位置在中文语境下读起来通顺，别出现"个文档 3 找到"这种。

3.2 硬编码字符串怎么处理

硬编码的字符串处理起来麻烦一些，因为它在 JS 代码里，改动存在风险。我的原则是：只改纯展示用的，任何参与逻辑判断的一律不动。

怎么判断？看这个字符串有没有被用于比较、拼接成键名、当作参数传给函数。举个典型例子，代码里可能有if (status === "Connected")这种判断，界面上也显示"Connected"，这时候你要是把字符串改成"已连接"，判断逻辑立刻失效，界面会一直显示断开状态。所以看到字符串出现在比较运算、switch 分支、对象键名里，直接跳过。

安全的改法是找那些明确传给渲染组件的属性，比如title="Connect"、label="Database"、placeholder="Search"。这类改动风险低，即使翻译不准确也只是显示问题，不会影响功能。改的时候建议一次改一个模块，改完立刻启动验证，别一口气改两百处然后启动失败去猜是哪一处的问题。

3.3 翻译量估算与分批推进

Compass 的界面文案量不算小，我粗略数过一个版本，国际化文件里的键大概在两千到三千条之间，加上硬编码的零散字符串，全部翻完是个体力活。所以必须分批，别想着一次到位。

第一批翻完就能拿给同事试用了，反馈会集中在术语是否顺口、按钮文字会不会溢出这两个问题上。按钮溢出的问题特别常见，英文一个单词翻成中文四个字，按钮宽度不够就挤成两行或者被截断，视觉上很难看。解决办法有两个：一是尽量用短词，比如"连接"而不是"建立连接"；二是找到样式文件里的宽度定义，适当放宽，但后者改动会影响布局，谨慎。

3.4 重新打包与完整性校验的处理

改完文件要打回去。命令很简单：

npx @electron/asar pack app_src app.asar

打包的时候有两个坑。第一个是路径问题，必须在app_src的父目录执行，或者用绝对路径，否则打出来的归档内部结构会多一层目录，程序加载时找不到入口文件，表现是启动直接白屏。第二个是app.asar.unpacked的处理，打包命令默认不会自动处理，需要看看原来的归档里哪些文件是 unpacked 的，打包时排除掉，保持结构一致。

打回去之后就是关键时刻：启动试试。如果启动正常，说明没有完整性校验或者校验没生效；如果直接闪退或者报错，那就是撞上完整性校验了。较新版本的 Electron 支持把 asar 的哈希摘要记录在可执行文件或者应用包的配置文件里，程序启动时会比对这个摘要，对不上就拒绝加载。

应对办法有两个，我推荐第二个。

办法一是重新计算摘要并写回去。macOS 上是应用包里的Info.plist，找到记录 asar 完整性的那个键，把新的哈希值填进去；Windows 上记录在可执行文件的资源段里，改起来更麻烦一些。这个办法的技术门槛不低，而且每次改动都要重算一遍，容易出错。

办法二是绕开 asar 机制本身。Electron 在加载应用时，会优先查找resources/app目录，存在就直接用目录，不存在才去读app.asar。所以只要把解包出来的app_src重命名为app放进resources，同时把原来那个app.asar挪走或者改名，程序就会从目录加载，asar 完整性校验也就无从谈起。这个办法的副作用是程序启动会稍微慢一点点，因为读几千个小文件比读一个大归档费劲，实际体感差别不大。

cd resources mv app.asar app.asar.bak mv app_src app

改完之后 macOS 上还要处理一下应用包的签名状态，因为内容变了，原有的签名校验会失败。自己用的机器上可以临时重新签名成 ad-hoc 的：

codesign --force --deep --sign - /Applications/Compass.app

这一步不做的话，系统可能直接提示应用损坏。Linux 和 Windows 上没有这个环节，改完直接启动就行。

4. 常见问题排查实录

这一节是我踩坑最多的地方，基本每个问题都至少花了我一个小时以上。整理成清单形式，遇到类似症状可以直接对照。

4.1 启动白屏、菜单栏消失、直接闪退

白屏是最常见的症状，八成是资源路径错了。原因可能是打包时多了一层目录，也可能是你把app目录放错了位置。检查方法：进开发者工具看控制台报错，如果是 404 一类，就是路径问题；如果是语法错误，就是 JSON 文件格式坏了，比如多了一个逗号、少了一个引号，这种错误肉眼很难发现，用工具校验一下：

node -e "JSON.parse(require('fs').readFileSync('语言包文件路径','utf8'))"

菜单栏消失通常是主进程代码报错。主进程出错时渲染进程还能起来，所以表现为"窗口有内容但顶部菜单没了"。这时候去看终端输出，或者从命令行启动程序看日志，报错信息会直接打出来。

闪退且没有任何提示，基本就是完整性校验或者签名问题。先按上一节的办法换成目录加载，再不行就检查系统日志，macOS 上用控制台应用看崩溃报告，Windows 上看事件查看器，日志里会写清楚是哪个环节挂的。

4.2 文案改了但界面没变化

这个问题的原因有四种，按概率从高到低排：

第一种，改了但没生效。确认打包时间对不对，确认程序加载的是你改的那份文件而不是备份。有个简单办法：故意把一个词改成明显的错别字，看看界面上出不出现，出现了说明路径对了，不出现说明你在改一个程序根本不读的文件。

第二种，文案来自服务端或者数据库。Compass 里有一部分内容是从连接的实例读出来的，比如数据库名、集合名、字段名，这些不该翻也不能翻。如果你发现某个"文案"怎么改都不变，先确认它是不是数据本身。

第三种，翻译被硬编码覆盖。有些组件先用国际化取词，取不到就回退到硬编码的英文，这种情况要两处都改。

第四种，界面用了缓存。Electron 的应用有时候会缓存渲染资源，清一下缓存目录或者换个用户配置再试。

4.3 功能异常类问题速查

这里要特别提醒隔离版的一个专属坑：有人在排查功能异常时，看到控制台报某个模块找不到，就顺手从普通版里把那个模块拷过来，想着"补全功能"。这么做会让隔离版的网络行为发生变化，本来是设计上不联网的组件被激活了，轻则启动报错，重则在封闭网络里反复重试导致界面卡顿。隔离版的模块缺失是有意为之，看到缺模块的报错，先判断是不是自己改动引起的，如果不是，放着别管。

4.4 版本升级之后汉化全部失效

这是必然会发生的事，不用惊讶。升级会用新的app.asar覆盖旧的，如果你的方案是把app.asar换成app目录，升级后会出现两个都存在的局面，程序优先加载目录，结果是新版本的功能配上旧版本的界面，可能直接崩。所以升级前先清理自己的改动，恢复原始状态再升级，升级完成后再重新走一遍汉化流程。

为了减少重复劳动，我现在的做法是把所有改动整理成"补丁集"：一个目录存语言包 JSON，一个脚本存需要做的文本替换规则，一个脚本负责解包、应用改动、打包。升级后跑一遍脚本，五分钟搞定。补丁集要跟着版本号走，不同版本的键可能增删，应用补丁时如果发现某个键在新版本里已经不存在了，脚本要能跳过而不是报错中断。

5. 让这套流程可持续的几个做法

手动改一次不算本事，能长期维护才算。这一节讲的是我摸索出来的工程化做法，核心思路是把"改文件"变成"跑脚本"。

5.1 用脚本固化整个流程

一个够用的脚本大概分四步：解包、应用语言包、应用文本替换规则、打包并校验。语言包部分最简单，直接把准备好的 JSON 覆盖过去就行。文本替换规则用数组配置，每条包含文件匹配模式、原文、译文，脚本遍历执行。

// 示意脚本，实际路径按你的环境调整 const fs = require('fs'); const path = require('path'); const asar = require('@electron/asar'); const SRC = './app_src'; const OUT = './app.asar'; // 1. 覆盖语言包 const localeFile = path.join(SRC, 'lib', 'i18n', 'zh-CN.json'); fs.copyFileSync('./patch/zh-CN.json', localeFile); // 2. 应用文本替换规则 const rules = [ { file: 'lib/components/connect.js', from: '"Connect"', to: '"连接"' }, { file: 'lib/components/connect.js', from: '"Cancel"', to: '"取消"' } ]; for (const r of rules) { const p = path.join(SRC, r.file); if (!fs.existsSync(p)) continue; let s = fs.readFileSync(p, 'utf8'); s = s.split(r.from).join(r.to); fs.writeFileSync(p, s, 'utf8'); } // 3. 打包 asar.createPackage(SRC, OUT).then(() => { console.log('打包完成'); });

脚本跑之前记得先确认解包目录是干净的，别在上一次的残留上继续改，那样会越改越乱。我一般会在脚本开头加一步删除旧目录的操作，每次从头来。

5.2 翻译质量的几个土办法

术语一致性是汉化最容易翻车的地方。同一个 Collection，有人翻"集合"，有人翻"数据集"，界面上就乱了。解决办法是维护一份术语表，开工前定好，所有人按表来。常用的几个：

长度控制是另一个土办法：屏幕上量一下按钮的宽度，中文超过六个字的基本都会溢出，能压就压。像"Create Database"翻成"新建数据库"是五个字，还行；要是翻成"创建一个新的数据库"就太长了。

最后一个办法是找不熟悉这套工具的人试读。自己翻完看什么都顺眼，因为你知道原文是什么。找个没看过英文界面的同事，让他按界面提示做一遍建库、插文档、查数据的流程，卡在哪个词上就说明那个词翻得不够直白。

5.3 分发和使用的边界

改完的应用包，我的建议是只在内部环境使用，不要对外分发。原因有几个：一是修改后的包已经不再是最初发布的版本，出了任何问题都无法定位责任；二是原始许可和版权声明不能删改，你打包时如果把许可文件弄丢了，属于使用上的瑕疵；三是版本管理会变得很混乱，同事之间互相传包，最后谁也不知道自己装的是哪一版。

内部使用的话，我一般会在包名或者启动脚本里加个标记，比如在关于页面加一行"内部本地化版本，基于 X 版本修改"，方便排查问题时报版本。同时把补丁集和操作手册放在内网共享目录里，谁需要谁自己跑，比传安装包靠谱得多。

还有一点，别去改版本号和构建信息。有人为了"看起来像官方版"把版本号也改掉，后面升级的时候一比对完全对不上，排查问题的时间成本高得离谱。原样保留这些元信息，只在界面语言上做文章，是最稳妥的。