把官方 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)、无线、 全部弹窗、命令面板、日期与相对时间。内嵌商店为远程服务端渲染,不在范围内。
191 lines
9.2 KiB
Markdown
191 lines
9.2 KiB
Markdown
# 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/...`,**完全不会更新应用**。
|
||
必须组装成 `<root>/DEBIAN` + `<root>/opt` + `<root>/usr`。
|
||
* **权限要对齐**:构建根 755、`app.asar` 644,否则与原包逐项对比会不一致。
|
||
* **压缩格式**:官方包用 `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 弹窗 / 命令面板 / 日期与相对时间
|
||
* 实测结论:各页面除品牌名、设备型号、单位与系统属性名外,**无残留英文**
|
||
* 不做:内嵌商店(远程服务端渲染)
|