orca-zh-tw-installer 1.0.9 → 1.1.0

package/README.md

@@ -30,8 +30,11 @@
 |------|------|
 | **一鍵跨平臺安裝** | 透過 `npx` 自動偵測作業系統並完成替換 |
 | **自動破解白名單** | 突破官方限制，將 `zh-TW` 寫入前端與核心白名單 |
-| **專業工程術語** | 翻譯精修，針對台灣開發者習慣用語（如 Worktree、終端機） |
-| **無痛備份機制** | 安裝前自動備份原始檔案（`app.asar.bak`），確保環境安全 |
+| **解除繁中強制降級** | 官方新版會把 `zh-TW`／`zh-HK`／`zh-Hant` 明確打回英文，本包一併解除 |
+| **原生選單也中文化** | 除了介面，系統匣、原生選單、系統對話框（main process）同樣套用繁中 |
+| **專業工程術語** | 對照 VS Code 官方 zh-TW 語系包精修，術語一詞一譯（如 存放庫、終端機、Worktree）|
+| **安裝後自動驗證** | 重新封裝前檢查全部注入點，任一失敗即中止且不改動 `app.asar`，不會「安裝成功卻沒效果」|
+| **無痛備份機制** | 首次安裝自動備份 `app.asar.bak`；重複執行會偵測既有補丁，不會用已修補版覆蓋乾淨備份 |
 | **自動追蹤更新** | npm 發布機制確保未來套用更新時始終取得最新版本 |
 
 ---
@@ -45,11 +48,24 @@ npx orca-zh-tw
 ```
 
 腳本將自動執行以下流程：
-1. 自動定位作業系統對應的 Orca 安裝路徑。
-2. 備份官方 `app.asar`。
-3. 解包並破解主程式與渲染器（Renderer）語言限制。
-4. 注入 11,000 句繁體中文字典檔。
-5. 重新封裝。
+1. 自動定位作業系統對應的 Orca 安裝路徑並解包。
+2. 備份官方 `app.asar`（已含補丁時會保留原本的乾淨備份）。
+3. 破解主程式（Main）語言限制與 locale 解析。
+4. 破解渲染器（Renderer）語言限制、下拉選單與 locale 解析。
+5. 注入 11,000 句繁體中文字典（ESM 給 Renderer、CJS 給 Main）。
+6. 驗證全部注入點後重新封裝。
+
+若想在不改動 Orca 的前提下先確認相容性（**可在 Orca 執行中安全使用**）：
+
+```bash
+npm run dry-run
+```
+
+安裝後可驗證實際封裝結果：
+
+```bash
+npm run verify
+```
 
 ---
 
@@ -89,9 +105,27 @@ npm start
 
 ### 檔案結構
 
-- `index.js`: 核心安裝腳本，處理 asar 解包、修補與封裝。
-- `zh-TW-nested.js`: Orca 前端讀取的最終編譯檔。
-- `orca_zh_TW_translation.json`: 原始語系字典檔，若欲改善翻譯可直接編輯此檔案。
+- `index.js`：核心安裝腳本，處理 asar 解包、修補、驗證與封裝。支援 `--dry-run`。
+- `orca_zh_TW_translation.json`：**唯一的翻譯來源**（扁平點分鍵）。改翻譯只改這個檔。
+- `zh-TW-nested.js`：由來源檔產生的 ESM 字典，供 Renderer 載入。**請勿手動編輯。**
+- `zh-TW-nested.cjs.js`：由來源檔產生的 CJS 字典，供 Main process 載入。**請勿手動編輯。**
+- `scripts/build-nested.js`：由 JSON 產生上述兩個字典檔。
+- `scripts/sweep-terms.js`：依術語鎖定表統一用詞，預設 dry-run。
+- `scripts/sweep-spacing.js`：中英之間補半形空格，預設 dry-run。
+- `scripts/verify-install.js`：驗證已安裝的 `app.asar` 是否含全部補丁與字典。
+
+### 改翻譯的流程
+
+`zh-TW-nested.js` 與 `zh-TW-nested.cjs.js` 都是**產生物**，編輯 JSON 後必須重新建置，
+否則安裝時不會生效：
+
+```bash
+# 1. 編輯 orca_zh_TW_translation.json
+# 2. 重新產生字典檔（兩種格式）
+npm run build
+# 3. 套用
+npm start
+```
 
 ---
 

package/index.js

@@ -24,109 +24,183 @@ if (!fs.existsSync(orcaPath)) {
 }
 
 const asar = require('@electron/asar');
-const workDir = path.join(os.tmpdir(), 'orca-zh-tw-patcher');
+// --dry-run：解包、修補、驗證，但不備份也不重新打包。
+// 可在 Orca 執行中安全使用，用來確認 Orca 更新後錨點是否仍然有效。
+const DRY_RUN = process.argv.includes('--dry-run');
+const workDir = path.join(os.tmpdir(), DRY_RUN ? 'orca-zh-tw-patcher-dry' : 'orca-zh-tw-patcher');
 const unpackedDir = path.join(workDir, 'app.asar.unpacked');
 
+const MARK = 'UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW"';
+
+/**
+ * 修補器：每個修補都要宣告「如何判斷已完成」。
+ * 若錨點找不到且尚未完成，就記為失敗——絕不靜默略過。
+ */
+function createPatcher(label, filePath) {
+  let code = fs.readFileSync(filePath, 'utf8');
+  const ok = [];
+  const failed = [];
+  return {
+    label,
+    /**
+     * @param name  修補名稱（顯示用）
+     * @param done  (code) => boolean，判斷是否已修補過
+     * @param find  string | RegExp 錨點
+     * @param repl  取代內容
+     */
+    patch(name, done, find, repl) {
+      if (done(code)) { ok.push(`${name}（已存在）`); return; }
+      const before = code;
+      code = code.replace(find, repl);
+      if (code === before || !done(code)) failed.push(name);
+      else ok.push(name);
+    },
+    save() { fs.writeFileSync(filePath, code); },
+    get ok() { return ok; },
+    get failed() { return failed; },
+  };
+}
+
+// ── 共用修補：三處新版 Orca 才有的 zh-TW 阻擋點 ──────────────────────────
+// A. locale 白名單沒有 zh-TW
+// B. normalizeSupportedUiLocale() 明確把 zh-tw / zh-hk / zh-hant 打回 DEFAULT_UI_LOCALE("en")
+// C. resolveUiLocale() 沒有 zh-TW 分支，選了繁中會掉出 if 鏈變成 "en"
+function patchLocaleGate(p) {
+  p.patch('locale 白名單加入 zh-TW',
+    c => c.includes('const SUPPORTED_UI_LOCALES = ["en", "zh", "zh-TW", "ko", "ja", "es"]'),
+    'const SUPPORTED_UI_LOCALES = ["en", "zh", "ko", "ja", "es"];',
+    'const SUPPORTED_UI_LOCALES = ["en", "zh", "zh-TW", "ko", "ja", "es"];');
+
+  p.patch('解除 zh-tw/zh-hk/zh-hant 退回英文',
+    c => /tag\.startsWith\("zh-hant"\)\)\s*\{\s*return "zh-TW";/.test(c),
+    /(if \(tag\.startsWith\("zh-tw"\) \|\| tag\.startsWith\("zh-hk"\) \|\| tag\.startsWith\("zh-hant"\)\) \{\s*)return DEFAULT_UI_LOCALE;/,
+    '$1return "zh-TW";');
+
+  p.patch('resolveUiLocale 加入 zh-TW 分支',
+    c => c.includes('if (language === "zh-TW") {'),
+    /(if \(language === UI_LANGUAGE_CHINESE\) \{\s*return "zh";\s*\})/,
+    '$1\n  if (language === "zh-TW") {\n    return "zh-TW";\n  }');
+}
+
 async function patch() {
   try {
-    console.log('📦 1/5 正在備份官方 app.asar 並解包 (這可能需要數十秒)...');
-    fs.copyFileSync(orcaPath, orcaPath + '.bak');
-    
-    if (fs.existsSync(workDir)) {
-      fs.rmSync(workDir, { recursive: true, force: true });
-    }
+    console.log('📦 1/6 正在解包 app.asar (這可能需要數十秒)...');
+    if (fs.existsSync(workDir)) fs.rmSync(workDir, { recursive: true, force: true });
     fs.mkdirSync(workDir, { recursive: true });
-    
     asar.extractAll(orcaPath, unpackedDir);
 
-    console.log('🛠️ 2/5 正在破解主程式 (main process) 語言限制...');
     const mainFile = path.join(unpackedDir, 'out', 'main', 'index.js');
-    let mainCode = fs.readFileSync(mainFile, 'utf8');
-    
-    // 注入常數
-    if (!mainCode.includes('UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW"')) {
-      mainCode = mainCode.replace(
-        'const UI_LANGUAGE_CHINESE = "zh";',
-        'const UI_LANGUAGE_CHINESE = "zh";\nconst UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW";'
-      );
+    if (!fs.existsSync(mainFile)) {
+      throw new Error('找不到 out/main/index.js，Orca 可能已大幅更改架構！');
     }
-    // 注入白名單
-    if (mainCode.includes('UI_LANGUAGE_CHINESE') && !mainCode.includes('UI_LANGUAGE_TRADITIONAL_CHINESE,')) {
-      mainCode = mainCode.replace(
-        'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_KOREAN',
-        'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_TRADITIONAL_CHINESE,\n  UI_LANGUAGE_KOREAN'
-      );
+
+    // 只在「目前的 asar 尚未被修補」時更新備份，
+    // 否則重複執行會用已修補的版本覆蓋掉乾淨備份。
+    const alreadyPatched = fs.readFileSync(mainFile, 'utf8').includes(MARK);
+    const bakPath = orcaPath + '.bak';
+    if (DRY_RUN) {
+      console.log(`   ↳ [dry-run] 跳過備份。目前 app.asar ${alreadyPatched ? '已含' : '未含'}補丁。`);
+    } else if (alreadyPatched && fs.existsSync(bakPath)) {
+      console.log('   ↳ 偵測到目前 app.asar 已含補丁，保留既有的乾淨備份。');
+    } else {
+      fs.copyFileSync(orcaPath, bakPath);
+      console.log('   ↳ 已備份原始 app.asar → app.asar.bak');
     }
-    fs.writeFileSync(mainFile, mainCode);
 
-    console.log('🛠️ 3/5 正在破解渲染器 (renderer process) 語言限制...');
+    console.log('🛠️ 2/6 正在修補主程式 (main process) 語言限制...');
+    const mp = createPatcher('main process', mainFile);
+    mp.patch('注入 zh-TW 常數',
+      c => c.includes(MARK),
+      'const UI_LANGUAGE_CHINESE = "zh";',
+      'const UI_LANGUAGE_CHINESE = "zh";\nconst UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW";');
+    mp.patch('加入語言列舉白名單',
+      c => c.includes('UI_LANGUAGE_TRADITIONAL_CHINESE,'),
+      'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_KOREAN',
+      'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_TRADITIONAL_CHINESE,\n  UI_LANGUAGE_KOREAN');
+    patchLocaleGate(mp);
+    // main process 有自己的 LAZY_LOCALE_LOADERS（CJS require），需另外注入
+    mp.patch('注入 main process 字典 loader',
+      c => c.includes('"zh-TW": () => Promise.resolve()'),
+      /(zh: \(\) => Promise\.resolve\(\)\.then\(\(\) => require\("\.\/chunks\/zh-[A-Za-z0-9_-]+\.js"\)\))/,
+      '$1,\n  "zh-TW": () => Promise.resolve().then(() => require("./chunks/zh-TW-nested.js"))');
+    mp.save();
+
+    console.log('🛠️ 3/6 正在修補渲染器 (renderer process) 語言限制...');
     const assetsDir = path.join(unpackedDir, 'out', 'renderer', 'assets');
-    const files = fs.readdirSync(assetsDir);
-    const i18nFile = files.find(f => f.startsWith('I18nProvider-') && f.endsWith('.js'));
-    
+    const i18nFile = fs.readdirSync(assetsDir)
+      .find(f => f.startsWith('I18nProvider-') && f.endsWith('.js'));
     if (!i18nFile) {
-      throw new Error('找不到 I18nProvider 檔案，Orca 可能已經大幅更改架構！');
-    }
-    
-    const rendererPath = path.join(assetsDir, i18nFile);
-    let rendererCode = fs.readFileSync(rendererPath, 'utf8');
-
-    // 加入常數
-    if (!rendererCode.includes('UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW"')) {
-      rendererCode = rendererCode.replace(
-        'const UI_LANGUAGE_CHINESE = "zh";',
-        'const UI_LANGUAGE_CHINESE = "zh";\nconst UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW";'
-      );
-    }
-    // 加入下拉選單
-    if (!rendererCode.includes('labelKey: "settings.appearance.language.traditionalChinese"')) {
-      rendererCode = rendererCode.replace(
-        '{ value: UI_LANGUAGE_CHINESE, labelKey: "settings.appearance.language.chinese" },',
-        '{ value: UI_LANGUAGE_CHINESE, labelKey: "settings.appearance.language.chinese" },\n  { value: UI_LANGUAGE_TRADITIONAL_CHINESE, labelKey: "settings.appearance.language.traditionalChinese" },'
-      );
+      throw new Error('找不到 I18nProvider 檔案，Orca 可能已大幅更改架構！');
     }
-    // 加入 Enum 白名單
-    if (!rendererCode.includes('UI_LANGUAGE_TRADITIONAL_CHINESE,') && rendererCode.includes('UI_LANGUAGE_VALUES =')) {
-      rendererCode = rendererCode.replace(
-        'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_KOREAN',
-        'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_TRADITIONAL_CHINESE,\n  UI_LANGUAGE_KOREAN'
-      );
+    const rendererFile = path.join(assetsDir, i18nFile);
+    const rp = createPatcher('renderer', rendererFile);
+    rp.patch('注入 zh-TW 常數',
+      c => c.includes(MARK),
+      'const UI_LANGUAGE_CHINESE = "zh";',
+      'const UI_LANGUAGE_CHINESE = "zh";\nconst UI_LANGUAGE_TRADITIONAL_CHINESE = "zh-TW";');
+    rp.patch('加入語言列舉白名單',
+      c => c.includes('UI_LANGUAGE_TRADITIONAL_CHINESE,'),
+      'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_KOREAN',
+      'UI_LANGUAGE_CHINESE,\n  UI_LANGUAGE_TRADITIONAL_CHINESE,\n  UI_LANGUAGE_KOREAN');
+    rp.patch('加入語言下拉選單項目',
+      c => c.includes('labelKey: "settings.appearance.language.traditionalChinese"'),
+      '{ value: UI_LANGUAGE_CHINESE, labelKey: "settings.appearance.language.chinese" },',
+      '{ value: UI_LANGUAGE_CHINESE, labelKey: "settings.appearance.language.chinese" },\n  { value: UI_LANGUAGE_TRADITIONAL_CHINESE, labelKey: "settings.appearance.language.traditionalChinese" },');
+    rp.patch('加入語言名稱 fallback',
+      c => c.includes('[UI_LANGUAGE_TRADITIONAL_CHINESE]:'),
+      '[UI_LANGUAGE_CHINESE]: "中文（简体）",',
+      '[UI_LANGUAGE_CHINESE]: "中文（简体）",\n  [UI_LANGUAGE_TRADITIONAL_CHINESE]: "中文（繁體）",');
+    rp.patch('注入 renderer 字典 loader',
+      c => c.includes('"zh-TW": () => __vitePreload'),
+      /ko: \(\) => __vitePreload\(\(\) => import\("\.\/ko-[a-zA-Z0-9_-]+\.js"\), [^,]+, import\.meta\.url\),/,
+      '$& \n  "zh-TW": () => __vitePreload(() => import("./zh-TW-nested.js"), true ? [] : void 0, import.meta.url),');
+    patchLocaleGate(rp);
+    rp.save();
+
+    console.log('📂 4/6 正在植入繁體中文字典 (ESM + CJS 兩種格式)...');
+    const esmDict = path.join(__dirname, 'zh-TW-nested.js');
+    const cjsDict = path.join(__dirname, 'zh-TW-nested.cjs.js');
+    for (const f of [esmDict, cjsDict]) {
+      if (!fs.existsSync(f)) throw new Error(`找不到字典檔：${f}（請先執行 npm run build）`);
     }
-    // 加入 Fallback 文字
-    if (!rendererCode.includes('[UI_LANGUAGE_TRADITIONAL_CHINESE]:')) {
-      rendererCode = rendererCode.replace(
-        '[UI_LANGUAGE_CHINESE]: "中文（简体）",',
-        '[UI_LANGUAGE_CHINESE]: "中文（简体）",\n  [UI_LANGUAGE_TRADITIONAL_CHINESE]: "中文（繁體）",'
-      );
+    fs.copyFileSync(esmDict, path.join(assetsDir, 'zh-TW-nested.js'));
+    const chunksDir = path.join(unpackedDir, 'out', 'main', 'chunks');
+    fs.copyFileSync(cjsDict, path.join(chunksDir, 'zh-TW-nested.js'));
+
+    console.log('🔎 5/6 正在驗證所有注入點...');
+    const allFailed = [
+      ...mp.failed.map(n => `[main] ${n}`),
+      ...rp.failed.map(n => `[renderer] ${n}`),
+    ];
+    for (const p of [mp, rp]) {
+      for (const n of p.ok) console.log(`   ✅ [${p.label}] ${n}`);
     }
-    // 注入翻譯檔案 Loader
-    if (!rendererCode.includes('"zh-TW": () =>')) {
-      rendererCode = rendererCode.replace(
-        /ko: \(\) => __vitePreload\(\(\) => import\("\.\/ko-[a-zA-Z0-9_-]+\.js"\), [^,]+, import\.meta\.url\),/,
-        `$& \n  "zh-TW": () => __vitePreload(() => import("./zh-TW-nested.js"), true ? [] : void 0, import.meta.url),`
+    if (allFailed.length) {
+      for (const n of allFailed) console.error(`   ❌ ${n}`);
+      throw new Error(
+        `有 ${allFailed.length} 個注入點失敗，已中止且未改動你的 Orca。\n` +
+        '   這通常表示 Orca 更新後改了程式碼結構，需要更新本安裝包的錨點。'
       );
     }
-    fs.writeFileSync(rendererPath, rendererCode);
 
-    console.log('📂 4/5 正在植入 11,000 句繁體中文翻譯字典包...');
-    const dictSource = path.join(__dirname, 'zh-TW-nested.js');
-    if (!fs.existsSync(dictSource)) {
-      throw new Error(`找不到字典檔：${dictSource}`);
+    if (DRY_RUN) {
+      console.log('\n✅ [dry-run] 全部注入點驗證通過，未改動你的 Orca。');
+      console.log('   關閉 Orca 後執行 npm start 即可正式套用。\n');
+      fs.rmSync(workDir, { recursive: true, force: true });
+      return;
     }
-    fs.copyFileSync(dictSource, path.join(assetsDir, 'zh-TW-nested.js'));
 
-    console.log('🗜️ 5/5 正在重新打包 app.asar (這可能需要數十秒)...');
+    console.log('🗜️ 6/6 正在重新打包 app.asar (這可能需要數十秒)...');
     await asar.createPackage(unpackedDir, orcaPath);
-    
-    // 清理
     fs.rmSync(workDir, { recursive: true, force: true });
 
-    console.log('\n🎉 安裝成功！請完全關閉 Orca (右下角 Quit) 並重新啟動！');
+    console.log('\n🎉 安裝成功！請完全關閉 Orca (系統匣右鍵 Quit) 並重新啟動！');
     console.log('然後前往 Settings -> Appearance -> Language 切換為「中文（繁體）」。\n');
 
   } catch (err) {
     console.error('\n❌ 安裝過程中發生錯誤：', err.message);
-    console.error('已經為您保留了原始的 app.asar.bak 備份檔。');
+    console.error(`已保留原始備份：${orcaPath}.bak`);
+    process.exitCode = 1;
   }
 }