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
2026-10-11 18:09:36 +08:00
2026-10-11 18:09:36 +08:00
2026-10-11 18:09:36 +08:00

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. 排查"某处没汉化"

  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 弹窗 / 命令面板 / 日期与相对时间
  • 实测结论:各页面除品牌名、设备型号、单位与系统属性名外,无残留英文
  • 不做:内嵌商店(远程服务端渲染)
S
Description
sideQuest的汉化工具
Readme
26 MiB
Languages
JavaScript 74.8%
Shell 25.2%