# SideQuest 简体中文汉化工具包(sideQuest-cn) 把官方 SideQuest 桌面版(当前基线 **1.4.1**)汉化为简体中文,并产出可覆盖安装的 `.deb`。 **设计原则:不改任何上游源码。** 本目录是纯新增文件,`git merge` 主线时不会产生冲突; 所有"改动"都发生在**已编译产物的补丁层**,且全部集中在 `build.js` 里,可随时重放。 --- ## 0. 为什么不是"从源码编译" 上游把新版(1.4.x 新架构:`dist-electron/` + `dist/sidequest-desktop/`)的开发放在**私有仓库** `SideQuestVR/SideQuestDesktop`;公开仓库 `SideQuestVR/SideQuest` 的 master 停在 2026-05-19 的 `af2ac70`,仍是旧架构(`desktop-app/` + `electron/*.ts`),且 **v1.0.0~v1.4.1 十个 tag 全部指向 同一个 commit**。也就是说公开源码里根本没有 1.4.1 的实现。 因此本工具包走的是 **"解包官方安装包 → 运行时字典注入 → 重新打包"** 路线: * 不依赖源码,也不需要联网装依赖(asar 读写由 `asar.js` 纯 Node 实现) * 产物与官方二进制逐字节一致,只多了汉化层 * 上游一旦发新版,重新 `unpack` + `all` 即可(见 §5) --- ## 0.1 仓库分支结构 本仓库有两类分支,用途不同: | 分支 | 内容 | 用途 | | --- | --- | --- | | `main` | 只有本工具包 | 日常使用;补词条、重新构建都在这条线上 | | `upstream` | 完整的上游 SideQuest 代码与 git 历史(停在 `af2ac70` / 官方 1.4.1 基线) | 需要对照上游源码、对比差异或将来合并主线时用 | 因为工具包**直接给已编译产物打补丁**,不依赖上游源码,所以 `main` 不带上游代码也能独立工作。 需要看上游代码时:`git switch upstream`,回到工具包:`git switch main`。 上游仓库以 `github` 为 remote 名保存: ```bash git fetch github # 拉取上游最新提交 git log upstream..github/master # 看上游有哪些新提交 ``` ## 1. 目录内容 | 文件 | 说明 | | --- | --- | | `build.js` | 构建入口:`unpack` / `app` / `asar` / `deb` / `all` | | `asar.js` | 纯 Node 实现的 asar 打包/解包(无外部依赖) | | `engine.js` | **运行时汉化引擎**(注入到页面,翻译 DOM 文本与属性) | | `tail.js` | **主进程统一注入 hook**(追加到 `dist-electron/main.js` 末尾) | | `rules.json` | 动态文案正则规则(含 `$1` 捕获组) | | `dict-a…i.json` | 词典(共 ~1780 条;按提取批次分批,便于维护) | | `site.json` | 内嵌商店默认站点配置 | | `test-run.sh` | 隔离试运行(不动系统、不动真实配置) | | `stop-test.sh` | 停止试运行实例 | | `install.sh` | 覆盖安装(需 sudo,含哈希校验与自动备份) | | `verify.sh` | 安装后独立校验(不需要 sudo) | --- ## 2. 快速开始(完整流程) ```bash export SQ_ZH_HOME="$HOME/.sidequest-zh" # 工作目录,默认就是它;产物不落在仓库里 # ① 准备原版基线(只需一次):从官方 deb 解出原始 app 与打包结构 node build.js unpack ~/Downloads/SideQuest-1.4.1.deb # ② 构建:打补丁 → 出 asar → 出 deb node build.js all # 产物: $SQ_ZH_HOME/dist/SideQuest-1.4.1-zh.N-amd64.deb (+ .sha256) # $SQ_ZH_HOME/dist/app.asar.zh (+ .sha256) # ③ 先试运行确认(推荐;完全隔离,不碰系统与真实配置) bash ./test-run.sh # 默认 9223 端口,10 秒后打印已加载页面 bash ./stop-test.sh # ④ 覆盖安装(需要交互式 sudo) sudo bash ./install.sh bash ./verify.sh # 装完后独立复核 ``` `unpack` 也接受直接给 `app.asar`(此时只准备 app 基线,不产出 deb,适合只想换 asar 的场景)。 --- ## 3. 汉化是怎么生效的 ``` Electron 主进程 (dist-electron/main.js) └─ 末尾追加的 hook: app.on('web-contents-created', ...) └─ 对每个本地页面 (file:// 与 data:text/html) 注入 engine.js └─ 引擎遍历 DOM:文本节点 + placeholder/title/aria-label/alt + MutationObserver 兜底 Angular 重渲染 ``` 几个关键点: * **为什么用主进程 hook 而不是改 HTML**:应用有 7 个 overlay 页面是以 `data:text/html` 拼出来并带 `default-src 'none'` CSP 的,无法外链脚本;`index.html` 又没有 CSP。 统一 hook 一次覆盖全部窗口(包括以后新增的),所以不需要逐个 HTML 注入。 * **远程内容不注入**:内嵌商店(默认 `www.vrwanba.com`)是服务端渲染,属于另一个仓库的工作。 * **幂等**:只做「英文 → 中文」替换,译文不会被再次翻译;规则带"替换结果不得再次命中"的守卫, 因此可以安全处理 `1.2.3.4:5555 · last seen 5分钟前` 这种混排。 * **不误伤**:`script` / `style` / `code` / `pre` / `svg` 子树整体跳过; `mat-icon`、`.material-icons` 跳过(图标用的是 ligature 字形名,翻了就变方块); 支持 `translate="no"` 与 `data-sq-zh-skip` 显式豁免。 * **组合文案**:Angular 会把 `说明 + (Default: X)` 拼进同一个文本节点,引擎会拆开分别翻译再拼回, 而不是为每条说明写一条规则。 `build.js` 一共打了 4 类补丁,每处都要求**精确命中**,上游一变就直接报错而不是静默失效: | 补丁 | 作用 | 禁用方式 | | --- | --- | --- | | 注入 hook + engine | 汉化本体 | — | | `updater.js` `supportsAppUpdates()` | 禁用官方自动更新,避免中文界面被官方英文版静默覆盖 | 启动时加 `SQ_ZH_ALLOW_UPDATES=1` | | `site.json` → `webUrl` + `STORE_HOSTS` | 切换内嵌商店默认站点(白名单必须同步,否则 `assertAllowedStoreUrl` 拒绝加载) | 改 `site.json` | | Angular en-US 语言数据 + `Intl.RelativeTimeFormat` | 日期/相对时间中文化(`2小时前`、`2026/10/11`) | — | --- ## 4. 回滚 ```bash # 恢复官方英文版 sudo dpkg -i ~/Downloads/SideQuest-1.4.1.deb # 或者只还原 app.asar(install.sh 每次都会自动备份) sudo cp $SQ_ZH_HOME/backup/app.asar.before-install-<时间戳> /opt/SideQuest/resources/app.asar ``` `install.sh` 不会触碰 `~/.config/SideQuestDesktop`(登录态、设备绑定、已记住的无线设备都在这里; 商店会话在 `Partitions/sidequest-store`)。deb 的 `postrm` 也只删 `/usr/bin/sidequest` 软链。 --- ## 5. 上游发新版后怎么复用 ```bash node build.js unpack ~/Downloads/SideQuest-<新版本>.deb node build.js all bash ./test-run.sh # 确认没有回退 sudo bash ./install.sh ``` `build.js` 会在补丁点找不到原始代码时直接失败并指出位置,此时按提示更新对应补丁即可 (补丁函数集中在 `build.js` 的 `patch*()` 里,每个都自带失败诊断)。 补词条:改 `dict-*.json`(纯 JSON,键=英文原文,值=译文)或 `rules.json`(正则), 然后 `node build.js all`。**不需要重新 unpack。** --- ## 6. 排查"某处没汉化" 1. 用 `test-run.sh` 起隔离实例,确认目标文本确实存在 2. 若文本来自**动态拼接**(含变量),它通常是**单个文本节点**,需要写 `rules.json` 正则, 而不是词典条目;反之若被插值切成多段,则要用词典条目 3. 检查该元素是否命中豁免(图标 class / `code` / `pre` / `translate="no"`) 4. 设备页、应用列表、文件列表里的**真实数据**(Android 目录名 `DCIM`、应用名 `WhatsApp`、 `debug.hwui.*` 这类系统属性名)**故意不翻译**,翻译了反而看不懂、点不对 --- ## 7. 已踩过的坑(都已在脚本里规避) * **asar 不能走符号链接**:`resources/app.asar` 若是指向别处的软链,Electron 会静默加载失败 (退出码 1、无任何报错)。试运行脚本因此强制用实体文件。 * **`dpkg-deb --build` 的载荷根**:它把"除 `DEBIAN` 外的所有内容"当作载荷根。 若把载荷放在 `data/` 子目录,装完会变成 `/data/opt/...`,**完全不会更新应用**。 必须组装成 `/DEBIAN` + `/opt` + `/usr`。 * **权限要对齐**:构建根 755、`app.asar` 644,否则与原包逐项对比会不一致。 * **压缩格式**:官方包用 `xz`,新版 dpkg 默认改成 `zstd`,需显式 `-Zxz` 保持一致。 * **不要用 `pkill -f`**:模式会匹配到调用者自己的命令行(含 `busybox`/`bash` 的 cmdline), 导致脚本被自己杀掉。本工具包一律用 `/proc//exe` 精确匹配。 * **Electron 子进程会继承监听 socket**:父进程退出后,`adb` 等子进程可能仍占着 原来的调试端口,需要按 exe 清理。 * **版本号语义**:用 `1.4.1-zh.N`。注意 semver 下 `1.4.1 > 1.4.1-zh.N`,所以即使 重新启用更新器,官方版本也会把汉化版"降级"覆盖——这正是要禁用更新器的原因。 --- ## 8. 当前状态 * 基线版本:**1.4.1**(阶段产物 `1.4.1-zh.3`) * 覆盖范围:应用外壳全部页面 —— 主页 / 侧载 / 文件 / 应用 / 串流 / 设备设置 / 调试(Logcat) / 无线 / 全部 overlay 弹窗 / 命令面板 / 日期与相对时间 * 实测结论:各页面除品牌名、设备型号、单位与系统属性名外,**无残留英文** * 不做:内嵌商店(远程服务端渲染)