Files
cat-shark d3db80c27b SideQuest 简体中文汉化工具包
把官方 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)、无线、
全部弹窗、命令面板、日期与相对时间。内嵌商店为远程服务端渲染,不在范围内。
2026-10-11 18:09:36 +08:00

191 lines
9.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 弹窗 / 命令面板 / 日期与相对时间
* 实测结论:各页面除品牌名、设备型号、单位与系统属性名外,**无残留英文**
* 不做:内嵌商店(远程服务端渲染)