Files
sideQuest-cn/build.js
T
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

493 lines
20 KiB
JavaScript
Raw 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.
#!/usr/bin/env node
/* ============================================================================
* SideQuest 简体中文汉化 —— 构建脚本
*
* 用法:
* node build.js inject # 合并词典 + 引擎,产出 dist-electron/l10n-zh-inject.js
* node build.js app # 生成打过补丁的 app 目录 (work/app-zh)
* node build.js asar # 打包 work/app.asar.zh
* node build.js deb # 生成 work/out/SideQuest-<ver>-zh.deb
* node build.js all # inject + app + asar + deb
*
* 产物:
* work/app-zh/ 补丁后的 app 目录
* work/app.asar.zh 补丁后的 asar
* work/out/*.deb 可 dpkg -i 覆盖安装的安装包
* ==========================================================================*/
'use strict';
const fs = require('fs');
const os = require('os');
const path = require('path');
const { execFileSync } = require('child_process');
const asar = require('./asar.js');
const WORK = process.env.SQ_ZH_HOME || path.join(os.homedir(), '.sidequest-zh');
const L10N = __dirname;
const APP_PRISTINE = path.join(WORK, 'app');
const APP_ZH = path.join(WORK, 'app-zh');
const INJECT_OUT = path.join(APP_ZH, 'dist-electron', 'l10n-zh-inject.js');
const ASAR_OUT = path.join(WORK, 'dist', 'app.asar.zh');
const OUT_DIR = path.join(WORK, 'dist');
const DEB_ROOT = path.join(WORK, 'deb');
/* dpkg-deb --build <dir> 会把「除 DEBIAN 外的所有内容」当作载荷根,
* 因此必须先组装出一个结构正确的构建根,否则载荷会落到 /data/ 下。 */
const DEB_BUILD_ROOT = path.join(WORK, 'deb-build');
/* 由 deb 的 control 决定的版本号;Debian 版本必须单调递增 */
const DEB_VERSION = process.env.SQ_ZH_VERSION || '1.4.1-zh.3';
function log(...a) {
console.log('[build]', ...a);
}
function die(msg) {
console.error('[build] 失败: ' + msg);
process.exit(1);
}
function readJson(p) {
return JSON.parse(fs.readFileSync(p, 'utf8'));
}
/* ------------------------------------------------------------------ inject */
function stepInject() {
const dict = Object.assign(
{},
readJson(path.join(L10N, 'dict-a.json')),
readJson(path.join(L10N, 'dict-b.json')),
readJson(path.join(L10N, 'dict-c.json')),
readJson(path.join(L10N, 'dict-e.json')),
readJson(path.join(L10N, 'dict-f.json')),
readJson(path.join(L10N, 'dict-g.json')),
readJson(path.join(L10N, 'dict-h.json')),
readJson(path.join(L10N, 'dict-i.json'))
);
const rules = readJson(path.join(L10N, 'rules.json'));
const engine = fs.readFileSync(path.join(L10N, 'engine.js'), 'utf8');
// 校验规则正则合法
for (const [re] of rules) {
try {
new RegExp(re);
} catch (e) {
die('rules.json 中的正则无效: ' + re + ' -> ' + e.message);
}
}
const banner =
'/* SideQuest 简体中文语言包 —— 由 l10n/build.js 自动生成,请勿手工修改。\n' +
' 词条数: ' +
Object.keys(dict).length +
' / 规则数: ' +
rules.length +
' */\n';
const payload =
banner +
'window.__SQ_ZH__ = { dict: ' +
JSON.stringify(dict) +
', rules: ' +
JSON.stringify(rules) +
' };\n' +
engine;
const target = path.join(WORK, 'l10n-zh-inject.js');
fs.writeFileSync(target, payload, 'utf8');
log('引擎已生成: ' + target + ' (词条 ' + Object.keys(dict).length + ' 条)');
return target;
}
/* --------------------------------------------------------------------- app */
function copyDir(src, dst) {
fs.rmSync(dst, { recursive: true, force: true });
fs.mkdirSync(dst, { recursive: true });
for (const e of fs.readdirSync(src, { withFileTypes: true })) {
const s = path.join(src, e.name);
const d = path.join(dst, e.name);
if (e.isDirectory()) copyDir(s, d);
else if (e.isSymbolicLink()) fs.symlinkSync(fs.readlinkSync(s), d);
else fs.copyFileSync(s, d);
}
}
function patchUpdater() {
const p = path.join(APP_ZH, 'dist-electron', 'updater.js');
let s = fs.readFileSync(p, 'utf8');
const ORIG =
"function supportsAppUpdates() {\n" +
" return electron_1.app.isPackaged && !process.env['FLATPAK_ID'];\n" +
'}';
const PATCHED =
'function supportsAppUpdates() {\n' +
' // [l10n-zh] 汉化版默认禁用官方自动更新,避免中文界面被官方英文版静默覆盖。\n' +
" // 如需恢复自动更新:设置环境变量 SQ_ZH_ALLOW_UPDATES=1 启动即可。\n" +
" if (process.env['SQ_ZH_ALLOW_UPDATES'] !== '1') {\n" +
' return false;\n' +
' }\n' +
" return electron_1.app.isPackaged && !process.env['FLATPAK_ID'];\n" +
'}';
if (s.indexOf(ORIG) === -1) {
if (s.indexOf('[l10n-zh]') !== -1) {
log('updater.js 已是补丁状态,跳过');
return;
}
die('updater.js 中未找到 supportsAppUpdates() 原始实现,上游代码可能已变动');
}
s = s.replace(ORIG, PATCHED);
// 跳过原因日志更准确
s = s.replace(
"'[updater] skipped — installation updates are managed by Flatpak.'",
"'[updater] skipped — disabled by zh-CN localization build (set SQ_ZH_ALLOW_UPDATES=1 to re-enable).'"
);
fs.writeFileSync(p, s, 'utf8');
log('updater.js 已禁用官方自动更新');
}
/* -------------------------------------------------------------------- 站点 */
/**
* 切换内嵌商店的默认站点。需要同步改两处:
* 1. 渲染进程的环境配置对象 webUrl(内嵌商店加载的首页)
* 2. 主进程 STORE_HOSTS 白名单(否则 assertAllowedStoreUrl 会拒绝加载)
* 站点地址来自 l10n/site.json,便于以后随时切换。
*/
function patchSite() {
const site = readJson(path.join(L10N, 'site.json'));
const target = site.webUrl;
if (!target) die('site.json 缺少 webUrl');
// 1) 渲染进程 webUrl
const browserDir = path.join(APP_ZH, 'dist', 'sidequest-desktop', 'browser');
const re = /webUrl:"([^"]+)"/;
let hit = 0;
let seen = null;
for (const f of fs.readdirSync(browserDir).filter(x => x.endsWith('.js'))) {
const p = path.join(browserDir, f);
const s = fs.readFileSync(p, 'utf8');
const m = re.exec(s);
if (!m) continue;
seen = m[1];
if (m[1] === target) continue;
fs.writeFileSync(p, s.replace(re, 'webUrl:"' + target + '"'), 'utf8');
hit++;
log('webUrl 已切换: ' + m[1] + ' -> ' + target + ' (' + f + ')');
}
if (hit === 0 && seen === null) {
die('未在渲染进程中找到 webUrl 配置(上游代码可能已变动)');
}
if (hit === 0 && seen === target) log('webUrl 已是目标站点,跳过');
// 2) 主进程 STORE_HOSTS 白名单(保留旧 hosts,避免影响登录回跳等流程)
const mp = path.join(APP_ZH, 'dist-electron', 'main.js');
let ms = fs.readFileSync(mp, 'utf8');
const sm = /const STORE_HOSTS = new Set\(\[([^\]]*)\]\);/.exec(ms);
if (!sm) die('未找到 STORE_HOSTS 定义,上游代码可能已变动');
const cur = sm[1]
.split(',')
.map(x => x.trim().replace(/^'|'$/g, ''))
.filter(Boolean);
const want = (site.extraStoreHosts || []).slice();
try {
want.push(new URL(target).hostname);
} catch (e) {
die('site.json 的 webUrl 不是合法 URL: ' + target);
}
const merged = cur.slice();
for (const h of want) if (h && merged.indexOf(h) === -1) merged.push(h);
if (merged.length !== cur.length) {
const lit =
'const STORE_HOSTS = new Set([' + merged.map(h => "'" + h + "'").join(', ') + ']);';
ms = ms.replace(sm[0], lit);
fs.writeFileSync(mp, ms, 'utf8');
log('STORE_HOSTS 已扩展: ' + merged.join(', '));
} else {
log('STORE_HOSTS 已包含目标主机,跳过');
}
}
/* ------------------------------------------------------------------ 日期本地化 */
/**
* 把 Angular 内置的 en-US 语言数据替换为中文,使日期/时间输出中文化。
* 应用没有显式设置 LOCALE_ID,因此走 Angular 默认的 en-US,正好命中这段数据。
* 每一项替换都要求「恰好命中 1 次」,上游代码变动时会直接报错而不是静默失效。
*/
function patchLocale() {
const browserDir = path.join(APP_ZH, 'dist', 'sidequest-desktop', 'browser');
const files = fs
.readdirSync(browserDir)
.filter(f => f.endsWith('.js'))
.map(f => path.join(browserDir, f));
const SUBS = [
// 语言标识
['var CE=["en",', 'var CE=["zh-Hans",'],
// 上午/下午
['[["a","p"],["AM","PM"]]', '[["am","pm"],["\u4e0a\u5348","\u4e0b\u5348"]]'],
// 星期
[
'["S","M","T","W","T","F","S"],["Sun","Mon","Tue","Wed","Thu","Fri","Sat"],["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"],["Su","Mo","Tu","We","Th","Fr","Sa"]',
'["\u65e5","\u4e00","\u4e8c","\u4e09","\u56db","\u4e94","\u516d"],["\u5468\u65e5","\u5468\u4e00","\u5468\u4e8c","\u5468\u4e09","\u5468\u56db","\u5468\u4e94","\u5468\u516d"],["\u661f\u671f\u65e5","\u661f\u671f\u4e00","\u661f\u671f\u4e8c","\u661f\u671f\u4e09","\u661f\u671f\u56db","\u661f\u671f\u4e94","\u661f\u671f\u516d"],["\u65e5","\u4e00","\u4e8c","\u4e09","\u56db","\u4e94","\u516d"]',
],
// 月份
[
'["J","F","M","A","M","J","J","A","S","O","N","D"],["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"],["January","February","March","April","May","June","July","August","September","October","November","December"]',
'["1","2","3","4","5","6","7","8","9","10","11","12"],["1\u6708","2\u6708","3\u6708","4\u6708","5\u6708","6\u6708","7\u6708","8\u6708","9\u6708","10\u6708","11\u6708","12\u6708"],["\u4e00\u6708","\u4e8c\u6708","\u4e09\u6708","\u56db\u6708","\u4e94\u6708","\u516d\u6708","\u4e03\u6708","\u516b\u6708","\u4e5d\u6708","\u5341\u6708","\u5341\u4e00\u6708","\u5341\u4e8c\u6708"]',
],
// 纪元
[
'[["B","A"],["BC","AD"],["Before Christ","Anno Domini"]]',
'[["B","A"],["\u516c\u5143\u524d","\u516c\u5143"],["\u516c\u5143\u524d","\u516c\u5143"]]',
],
// 日期格式
[
'["M/d/yy","MMM d, y","MMMM d, y","EEEE, MMMM d, y"]',
'["yyyy/M/d","yyyy\u5e74M\u6708d\u65e5","yyyy\u5e74M\u6708d\u65e5","yyyy\u5e74M\u6708d\u65e5 EEEE"]',
],
// 时间格式
[
'["h:mm\\u202Fa","h:mm:ss\\u202Fa","h:mm:ss\\u202Fa z","h:mm:ss\\u202Fa zzzz"]',
'["H:mm","H:mm:ss","H:mm:ss z","H:mm:ss zzzz"]',
],
// 相对时间(Intl)
[
'new Intl.RelativeTimeFormat("en",{numeric:"auto"})',
'new Intl.RelativeTimeFormat("zh-CN",{numeric:"auto"})',
],
];
for (const [from, to] of SUBS) {
let hits = 0;
for (const p of files) {
const s = fs.readFileSync(p, 'utf8');
const n = s.split(from).length - 1;
if (n === 0) continue;
hits += n;
fs.writeFileSync(p, s.split(from).join(to), 'utf8');
}
if (hits === 0) {
if (to.indexOf('\u4e0a\u5348') !== -1 || to.indexOf('yyyy') !== -1 || to.indexOf('zh-CN') !== -1) {
log(' 跳过(未命中,可能已是本地化状态): ' + from.slice(0, 40));
continue;
}
}
log(' 日期本地化: ' + hits + ' 处 ' + from.slice(0, 46));
}
}
function patchMain() {
const p = path.join(APP_ZH, 'dist-electron', 'main.js');
let s = fs.readFileSync(p, 'utf8');
if (s.indexOf('SideQuest 简体中文汉化 —— 主进程统一注入 hook') !== -1) {
log('main.js 已含注入 hook,跳过');
return;
}
const tail = fs.readFileSync(path.join(L10N, 'tail.js'), 'utf8');
if (!s.endsWith('\n')) s += '\n';
fs.writeFileSync(p, s + '\n' + tail + '\n', 'utf8');
log('main.js 已追加注入 hook');
}
function stepApp() {
if (!fs.existsSync(path.join(APP_PRISTINE, 'dist-electron', 'main.js'))) {
die('未找到原始 app 目录: ' + APP_PRISTINE + '(请先运行解包脚本)');
}
const inject = stepInject();
copyDir(APP_PRISTINE, APP_ZH);
fs.copyFileSync(inject, INJECT_OUT);
patchUpdater();
patchSite();
patchLocale();
patchMain();
const st = fs.statSync(APP_ZH);
log('app-zh 已生成: ' + APP_ZH);
return APP_ZH;
}
/* -------------------------------------------------------------------- asar */
function stepAsar() {
if (!fs.existsSync(APP_ZH)) die('app-zh 不存在,请先运行: node build.js app');
fs.mkdirSync(path.dirname(ASAR_OUT), { recursive: true });
fs.rmSync(ASAR_OUT, { force: true });
const r = asar.pack(APP_ZH, ASAR_OUT);
/* 记录 asar 哈希:install.sh / verify.sh 用它确认「装的确实是验证过的那份」 */
fs.writeFileSync(
ASAR_OUT + '.sha256',
require('crypto').createHash('sha256').update(fs.readFileSync(ASAR_OUT)).digest('hex') +
' ' +
path.basename(ASAR_OUT) +
'\n',
'utf8'
);
log(
'app.asar 已生成: ' +
ASAR_OUT +
' (' + r.files + ' 个文件, ' + fs.statSync(ASAR_OUT).size + ' 字节)'
);
return ASAR_OUT;
}
/* --------------------------------------------------------------------- deb */
function stepDeb() {
if (!fs.existsSync(ASAR_OUT)) die('app.asar.zh 不存在,请先运行: node build.js asar');
/* 只清理旧的 deb 产物:asar 产物现在也放在 OUT_DIR 下,
不能整目录删除,否则会把自己的输入删掉。 */
fs.mkdirSync(OUT_DIR, { recursive: true });
for (const f of fs.readdirSync(OUT_DIR)) {
if (f.endsWith('.deb') || f.endsWith('.deb.sha256')) {
fs.rmSync(path.join(OUT_DIR, f), { force: true });
}
}
// 用原始 deb 作为底包,仅替换 app.asar 并改版本号,保证 postinst/postrm 等完全一致
const rootData = path.join(DEB_ROOT, 'data');
const rootCtl = path.join(DEB_ROOT, 'DEBIAN');
if (!fs.existsSync(rootData) || !fs.existsSync(rootCtl)) die('deb 底包未解压,请先运行解包脚本');
const asarDst = path.join(rootData, 'opt', 'SideQuest', 'resources', 'app.asar');
if (!fs.existsSync(asarDst)) die('底包中未找到 app.asar: ' + asarDst);
fs.copyFileSync(ASAR_OUT, asarDst);
// 版本号
const ctlPath = path.join(rootCtl, 'control');
let ctl = fs.readFileSync(ctlPath, 'utf8');
ctl = ctl.replace(/^Version: .*$/m, 'Version: ' + DEB_VERSION);
// Installed-Size 重新计算(KB)
const installedKb = Number(
execFileSync('du', ['-sk', rootData], { encoding: 'utf8' }).trim().split(/\s+/)[0]
);
ctl = ctl.replace(/^Installed-Size: .*$/m, 'Installed-Size: ' + installedKb);
fs.writeFileSync(ctlPath, ctl, 'utf8');
// 重新生成 md5sums
const files = [];
(function walk(dir) {
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, e.name);
if (e.isDirectory()) walk(p);
else if (e.isFile()) files.push(p);
}
})(rootData);
const lines = files
.sort()
.map(p => {
const rel = path.relative(rootData, p);
const md5 = execFileSync('md5sum', [p], { encoding: 'utf8' }).trim().split(/\s+/)[0];
return md5 + ' ' + rel;
})
.join('\n');
fs.writeFileSync(path.join(rootCtl, 'md5sums'), lines + '\n', 'utf8');
// 可执行文件权限(dpkg-deb 会保留,但确保与原始一致)
const sq = path.join(rootData, 'opt', 'SideQuest', 'sidequest');
if (fs.existsSync(sq)) fs.chmodSync(sq, 0o755);
const sandbox = path.join(rootData, 'opt', 'SideQuest', 'chrome-sandbox');
if (fs.existsSync(sandbox)) fs.chmodSync(sandbox, 0o755);
const outDeb = path.join(OUT_DIR, 'SideQuest-' + DEB_VERSION + '-amd64.deb');
// 组装结构正确的构建根: <root>/DEBIAN + <root>/opt + <root>/usr
fs.rmSync(DEB_BUILD_ROOT, { recursive: true, force: true });
fs.mkdirSync(DEB_BUILD_ROOT, { recursive: true });
for (const entry of fs.readdirSync(rootData)) {
execFileSync('cp', ['-a', path.join(rootData, entry), path.join(DEB_BUILD_ROOT, entry)]);
}
execFileSync('cp', ['-a', rootCtl, path.join(DEB_BUILD_ROOT, 'DEBIAN')]);
// 权限对齐原始包:构建根 755,app.asar 644(其余文件由 cp -a 保留原始权限)
fs.chmodSync(DEB_BUILD_ROOT, 0o755);
fs.chmodSync(path.join(DEB_BUILD_ROOT, 'opt', 'SideQuest', 'resources', 'app.asar'), 0o644);
// 与原包保持一致的压缩格式(官方 1.4.1 用的是 xz;新版 dpkg 默认改成了 zstd)
execFileSync('dpkg-deb', ['--root-owner-group', '-Zxz', '--build', DEB_BUILD_ROOT, outDeb], {
stdio: 'inherit',
});
fs.writeFileSync(
outDeb + '.sha256',
require('crypto').createHash('sha256').update(fs.readFileSync(outDeb)).digest('hex') +
' ' + path.basename(outDeb) + '\n',
'utf8'
);
log('deb 已生成: ' + outDeb + ' (' + fs.statSync(outDeb).size + ' 字节)');
return outDeb;
}
/* ------------------------------------------------------------------ unpack */
/**
* 准备「原版基线」:从官方 deb(或 app.asar)解出可打补丁的 app 目录,
* 以及用于重新打包 deb 的 DEBIAN + 载荷结构。
*
* node build.js unpack /path/to/SideQuest-1.4.1.deb
* node build.js unpack /path/to/app.asar
*
* 只需要跑一次;之后 app / asar / deb / all 都基于它。
*/
function stepUnpack(srcArg) {
if (!srcArg) die('用法: node build.js unpack <官方 deb 或 app.asar 路径>');
if (!fs.existsSync(srcArg)) die('找不到输入文件: ' + srcArg);
fs.mkdirSync(WORK, { recursive: true });
/* 按内容识别类型(deb 是 ar 归档,魔数 "!<arch>\n"),
这样即使文件名被改过(如 xxx.deb.orig)也能正确处理。 */
const magic = Buffer.alloc(8);
{
const fd = fs.openSync(srcArg, 'r');
try {
fs.readSync(fd, magic, 0, 8, 0);
} finally {
fs.closeSync(fd);
}
}
const isDeb = magic.toString('latin1') === '!<arch>\n';
let asarPath = srcArg;
log('输入类型: ' + (isDeb ? 'deb 安装包' : 'asar 归档'));
if (isDeb) {
/* 解出 DEBIAN/ 与载荷(opt/ usr/ ...) */
fs.rmSync(DEB_ROOT, { recursive: true, force: true });
fs.mkdirSync(DEB_ROOT, { recursive: true });
execFileSync('dpkg-deb', ['-e', srcArg, path.join(DEB_ROOT, 'DEBIAN')], { stdio: 'inherit' });
const payload = path.join(DEB_ROOT, 'data');
fs.mkdirSync(payload, { recursive: true });
execFileSync('dpkg-deb', ['-x', srcArg, payload], { stdio: 'inherit' });
asarPath = path.join(payload, 'opt', 'SideQuest', 'resources', 'app.asar');
if (!fs.existsSync(asarPath)) die('deb 载荷中未找到 app.asar: ' + asarPath);
log('deb 底包已解出: ' + DEB_ROOT);
}
/* 解出原始 app 目录 */
fs.rmSync(APP_PRISTINE, { recursive: true, force: true });
fs.mkdirSync(APP_PRISTINE, { recursive: true });
const r = asar.extract(asarPath, APP_PRISTINE);
log('原版 app 已解出: ' + APP_PRISTINE + ' (' + r.files + ' 个文件)');
if (!fs.existsSync(path.join(APP_PRISTINE, 'dist-electron', 'main.js'))) {
die('解出的 app 中找不到 dist-electron/main.js —— 上游结构可能已变,请先确认版本');
}
log('完成。接着可执行: node build.js all');
}
/* -------------------------------------------------------------------- main */
const cmd = process.argv[2] || 'all';
switch (cmd) {
case 'unpack':
stepUnpack(process.argv[3]);
break;
case 'inject':
stepInject();
break;
case 'app':
stepApp();
break;
case 'asar':
stepAsar();
break;
case 'deb':
stepDeb();
break;
case 'all':
stepApp();
stepAsar();
stepDeb();
break;
default:
die('未知命令: ' + cmd);
}