把官方 SideQuest 桌面版(基线 1.4.1)汉化为简体中文,并产出可覆盖安装的 deb。 不修改任何上游源码:所有改动集中在 build.js 的补丁层,作用于已编译产物 (dist-electron 与 dist/sidequest-desktop),因此本工具包可独立于上游代码工作。 主要内容: - 运行时汉化引擎 engine.js + 主进程统一注入 hook tail.js (应用有 7 个 data:text/html overlay 页且带严格 CSP,故用主进程 hook 一次覆盖全部窗口) - 词典 1806 条(dict-a…i.json)+ 动态规则 137 条(rules.json) - 纯 Node 实现的 asar 打包/解包 asar.js,零外部依赖 - 构建/试运行/安装/校验脚本 覆盖范围:主页、侧载、文件、应用、串流、设备设置、调试(Logcat)、无线、 全部弹窗、命令面板、日期与相对时间。内嵌商店为远程服务端渲染,不在范围内。
9.2 KiB
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 名保存:
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. 快速开始(完整流程)
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. 回滚
# 恢复官方英文版
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. 上游发新版后怎么复用
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. 排查"某处没汉化"
- 用
test-run.sh起隔离实例,确认目标文本确实存在 - 若文本来自动态拼接(含变量),它通常是单个文本节点,需要写
rules.json正则, 而不是词典条目;反之若被插值切成多段,则要用词典条目 - 检查该元素是否命中豁免(图标 class /
code/pre/translate="no") - 设备页、应用列表、文件列表里的真实数据(Android 目录名
DCIM、应用名WhatsApp、debug.hwui.*这类系统属性名)故意不翻译,翻译了反而看不懂、点不对
7. 已踩过的坑(都已在脚本里规避)
- asar 不能走符号链接:
resources/app.asar若是指向别处的软链,Electron 会静默加载失败 (退出码 1、无任何报错)。试运行脚本因此强制用实体文件。 dpkg-deb --build的载荷根:它把"除DEBIAN外的所有内容"当作载荷根。 若把载荷放在data/子目录,装完会变成/data/opt/...,完全不会更新应用。 必须组装成<root>/DEBIAN+<root>/opt+<root>/usr。- 权限要对齐:构建根 755、
app.asar644,否则与原包逐项对比会不一致。 - 压缩格式:官方包用
xz,新版 dpkg 默认改成zstd,需显式-Zxz保持一致。 - 不要用
pkill -f:模式会匹配到调用者自己的命令行(含busybox/bash的 cmdline), 导致脚本被自己杀掉。本工具包一律用/proc/<pid>/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 弹窗 / 命令面板 / 日期与相对时间
- 实测结论:各页面除品牌名、设备型号、单位与系统属性名外,无残留英文
- 不做:内嵌商店(远程服务端渲染)