@polang233/kiro-language-pack 0.0.0-stage → 1.2.1

package/scripts/lib/cli.mjs

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { spawnSync } from 'node:child_process';
+import { p, readJson } from './util.mjs';
+import { chineseLocale, systemLocale } from './system-locale.mjs';
+
+const COMMANDS = ['install', 'preview', 'status', 'restore'];
+
+export function parseCli(args) {
+  const options = {};
+  let command;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--version' || arg === '-v') { options.version = true; continue; }
+    if (arg === '--yes' || arg === '-y') { options.yes = true; continue; }
+    if (arg.startsWith('--')) {
+      const equal = arg.indexOf('=');
+      const key = arg.slice(2, equal < 0 ? undefined : equal);
+      if (!['locale', 'dir', 'install-dir'].includes(key)) throw new Error(`未知参数：${arg}`);
+      const value = equal < 0 ? args[++i] : arg.slice(equal + 1);
+      if (!value || value.startsWith('--')) throw new Error(`--${key} 需要一个值。`);
+      const canonical = key === 'install-dir' ? 'dir' : key;
+      if (options[canonical] !== undefined) throw new Error(`--${canonical} 只能指定一次。`);
+      options[canonical] = value;
+    } else {
+      if (command || !COMMANDS.includes(arg)) throw new Error(`未知命令：${arg}`);
+      command = arg;
+    }
+  }
+  if (options.locale && !['auto', 'zh-cn', 'zh-tw'].includes(options.locale)) {
+    throw new Error('语言可选 auto、zh-cn、zh-tw。');
+  }
+  return { command: command ?? 'install', options };
+}
+
+export async function runCli(product, args = process.argv.slice(2)) {
+  try {
+    const { command, options } = parseCli(args);
+    const name = product === 'cursor' ? 'Cursor' : 'Kiro';
+    const pkg = readJson(p('package.json'));
+    if (options.version) { console.log(pkg.version); return; }
+    if (options.help) {
+      console.log(`${name} 中文语言包\n\nnpx ${pkg.name}@latest [install|preview|status|restore] [选项]\n\n不带命令时安装。先完全退出 ${name}，完成后重新打开。\n  --locale=zh-cn|zh-tw  指定简体或繁体，默认按系统语言选择\n  --dir=<路径>          指定安装目录，macOS 可填 ${name}.app\n  --yes                 多份安装时要求用 --dir 指定，跳过选择\n  --help                显示帮助\n  --version             显示版本\n\n台湾、香港、澳门及 zh-Hant 默认繁体，其他系统默认简体。\nrestore 恢复程序文件，显示语言和语言扩展可在 ${name} 内调整。`);
+      return;
+    }
+    const paths = await import(`./${product}-paths.mjs`);
+    let dir = options.dir;
+    if (!dir) {
+      const installs = product === 'cursor' ? paths.findCursorInstalls() : paths.findKiroInstalls();
+      if (installs.length === 1) dir = installs[0].installRoot;
+      else if (installs.length > 1) {
+        const list = installs.map((item, i) => `  ${i + 1}. ${item.installRoot}`).join('\n');
+        if (options.yes || !process.stdin.isTTY || !process.stdout.isTTY) {
+          throw new Error(`找到多份 ${name}，请用 --dir 指定：\n${list}`);
+        }
+        console.log(`选择 ${name} 安装目录：\n${list}`);
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        let answer;
+        try { answer = await rl.question('输入编号：'); } finally { rl.close(); }
+        if (!/^\d+$/.test(answer.trim())) throw new Error('已取消。');
+        dir = installs[Number(answer.trim()) - 1]?.installRoot;
+        if (!dir) throw new Error('已取消。');
+      } else throw new Error(`找不到 ${name}。请用 --dir 指定安装目录。`);
+    }
+    dir = path.resolve(dir);
+    if (/\.app$/i.test(dir)) dir = path.join(dir, 'Contents');
+    const appRoot = path.join(dir, 'resources', 'app');
+    if (!fs.existsSync(path.join(appRoot, 'package.json'))) throw new Error(`安装目录中找不到 resources/app：${dir}`);
+    const flags = [`--${product === 'cursor' ? 'dir' : 'install-dir'}=${dir}`];
+    if (command === 'restore') flags.push(product === 'cursor' ? '--undo' : '--restore');
+    else if (command === 'status') flags.push('--status');
+    else {
+      const config = readJson(p('config.json'));
+      const info = product === 'cursor' ? paths.readCursorInfo(appRoot) : paths.readKiroInfo(appRoot);
+      const version = product === 'cursor' ? info.cursorVersion : info.kiroVersion;
+      const verified = product === 'cursor' ? config.target.verifiedCursorVersions : config.target.verifiedKiroVersions;
+      if (version && !verified.includes(version)) console.warn(`${name} ${version} 尚未验证，新增或变更的文案可能显示英文。`);
+      const detected = options.locale && options.locale !== 'auto' ? null : systemLocale();
+      const locale = detected === null ? options.locale : chineseLocale(detected);
+      console.log(`语言：${locale === 'zh-tw' ? '繁體中文' : '简体中文'}${detected === null ? '' : `（系统 ${detected}）`}。可用 --locale=zh-cn 或 --locale=zh-tw 更改。`);
+      flags.push(`--locale=${locale}`);
+      if (command === 'install') {
+        const vsix = [p('assets', 'language-pack.vsix'), p('dist', `${config.namePrefix}-${config.version}.vsix`)]
+          .find((file) => fs.existsSync(file));
+        if (!vsix) throw new Error('包内缺少语言扩展。源码运行前请执行 npm run package:npm。');
+        flags.push(`--vsix=${vsix}`);
+        if (product === 'kiro') flags.push('--apply');
+      } else if (product === 'cursor') flags.push('--preview');
+    }
+    flags.push('--yes');
+    const script = product === 'cursor' ? 'translate-install.mjs' : 'patch-install.mjs';
+    const result = spawnSync(process.execPath, [p('scripts', script), ...flags], { stdio: 'inherit', windowsHide: true });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+  } catch (err) {
+    console.error(`安装工具：${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/lib/kiro-paths.mjs

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readJson } from './util.mjs';
+
+/**
+ * Kiro is a Code OSS fork, so the desktop layout matches VS Code:
+ *   <install>/resources/app/package.json
+ *   <install>/resources/app/product.json
+ *   <install>/resources/app/out/            core NLS metadata
+ *   <install>/resources/app/extensions/     built-in extensions
+ * On macOS <install> is Kiro.app/Contents.
+ */
+function candidateRoots() {
+  const home = os.homedir();
+  const env = process.env;
+  const roots = [];
+
+  if (env.KIRO_INSTALL_DIR) roots.push(env.KIRO_INSTALL_DIR);
+
+  if (process.platform === 'win32') {
+    const bases = [
+      env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, 'Programs'),
+      env.ProgramFiles,
+      env['ProgramFiles(x86)'],
+      path.join(home, 'AppData', 'Local', 'Programs')
+    ].filter(Boolean);
+    for (const base of bases) {
+      roots.push(path.join(base, 'Kiro'), path.join(base, 'kiro'), path.join(base, 'Kiro IDE'));
+    }
+    // Portable or custom installs are common on Windows; probe fixed drives.
+    for (const drive of ['C', 'D', 'E', 'F', 'G']) {
+      roots.push(`${drive}:\\Kiro`, `${drive}:\\Program Files\\Kiro`, `${drive}:\\AI\\Kiro`);
+    }
+  } else if (process.platform === 'darwin') {
+    roots.push(
+      '/Applications/Kiro.app/Contents',
+      path.join(home, 'Applications', 'Kiro.app', 'Contents')
+    );
+  } else {
+    roots.push(
+      '/usr/share/kiro',
+      '/opt/Kiro',
+      '/opt/kiro',
+      '/usr/lib/kiro',
+      path.join(home, '.local', 'share', 'kiro')
+    );
+  }
+  return roots;
+}
+
+/**
+ * Every Kiro install the probe finds, deduplicated by resolved path. Several are
+ * common in practice: a per-user install plus a portable copy, or two versions kept
+ * side by side. Callers that must pick one show this list instead of guessing.
+ */
+export function findKiroInstalls() {
+  const seen = new Set();
+  const found = [];
+  for (const root of candidateRoots()) {
+    const appRoot = path.join(root, 'resources', 'app');
+    if (!fs.existsSync(path.join(appRoot, 'package.json'))) continue;
+    const key = path.resolve(appRoot).toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    found.push({ installRoot: path.resolve(root), appRoot });
+  }
+  return found;
+}
+
+export function findKiroInstall() {
+  return findKiroInstalls()[0] ?? null;
+}
+
+export function readKiroInfo(appRoot) {
+  const pkg = readJson(path.join(appRoot, 'package.json'), {});
+  const product = readJson(path.join(appRoot, 'product.json'), {});
+  return {
+    appRoot,
+    // Kiro's own release number, e.g. 1.0.228
+    kiroVersion: product.version ?? pkg.version ?? null,
+    // Underlying Code OSS version - this is what engines.vscode must satisfy
+    vscodeVersion: product.vsCodeVersion ?? pkg.version ?? null,
+    commit: product.commit ?? null,
+    quality: product.quality ?? null,
+    productName: product.nameLong ?? product.nameShort ?? pkg.name ?? null,
+    // Kiro defaults to the Open VSX registry
+    galleryUrl: product.extensionsGallery?.serviceUrl ?? null,
+    dataFolderName: product.dataFolderName ?? null
+  };
+}
+
+/** Where installed extensions live, the counterpart of ~/.vscode/extensions. */
+export function extensionsDir(dataFolderName) {
+  return path.join(os.homedir(), dataFolderName || '.kiro', 'extensions');
+}
+
+/** argv.json lives at ~/<dataFolderName>/argv.json and holds the display language. */
+export function argvJsonPath(dataFolderName) {
+  return path.join(os.homedir(), dataFolderName || '.kiro', 'argv.json');
+}
+
+/**
+ * Locate the core NLS metadata. Two layouts exist across Code OSS versions:
+ *   - current: out/nls.keys.json  [[moduleId, [key, ...]], ...]
+ *              out/nls.messages.json  [englishMessage, ...] in the same order
+ *   - legacy:  out/nls.metadata.json  { keys: {...}, messages: {...} }
+ */
+export function findCoreNlsMetadata(appRoot) {
+  const out = path.join(appRoot, 'out');
+  const metadata = path.join(out, 'nls.metadata.json');
+  const keys = path.join(out, 'nls.keys.json');
+  const messages = path.join(out, 'nls.messages.json');
+
+  if (fs.existsSync(metadata)) return { layout: 'metadata', metadata };
+  if (fs.existsSync(keys)) {
+    return { layout: 'keys', keys, messages: fs.existsSync(messages) ? messages : null };
+  }
+  return { layout: 'none' };
+}
+
+/**
+ * Enumerate built-in extensions. The returned `id` is `publisher.name` from the
+ * manifest, which is what contributes.localizations expects - note that it can
+ * differ from the folder name (kiro.kiro-agent on disk, kiro.kiroAgent as id).
+ */
+export function listBuiltinExtensions(appRoot) {
+  const dir = path.join(appRoot, 'extensions');
+  if (!fs.existsSync(dir)) return [];
+
+  const result = [];
+  for (const name of fs.readdirSync(dir)) {
+    const extDir = path.join(dir, name);
+    const manifest = path.join(extDir, 'package.json');
+    if (!fs.statSync(extDir).isDirectory() || !fs.existsSync(manifest)) continue;
+
+    const pkg = readJson(manifest, null);
+    if (!pkg?.name) continue;
+
+    result.push({
+      id: `${pkg.publisher || 'vscode'}.${pkg.name}`,
+      folder: name,
+      dir: extDir,
+      manifest,
+      version: pkg.version ?? null,
+      displayName: pkg.displayName ?? pkg.name,
+      hasNls: fs.existsSync(path.join(extDir, 'package.nls.json'))
+    });
+  }
+  return result.sort((a, b) => a.id.localeCompare(b.id));
+}

package/scripts/lib/markers.mjs

@@ -0,0 +1,43 @@
+/**
+ * Structural markers embedded in UI strings.
+ *
+ * These must survive translation byte for byte, otherwise the string renders
+ * incorrectly at runtime: a stale `{2}` shows up as the literal text "{2}", a
+ * translated `command:` target turns a link into dead text, and a missing
+ * `$(icon)` leaves a gap where an icon should be.
+ *
+ * Upstream baselines drift, because microsoft/vscode-loc tracks the current VS Code
+ * release while Kiro lags behind. Comparing markers against the English source
+ * shipped inside the Kiro build is what catches that drift.
+ */
+
+const PATTERNS = {
+  placeholder: /\{\d+\}/g,
+  icon: /\$\([a-z0-9-~]+\)/gi,
+  commandLink: /\(command:([^)\s]+)\)/g
+};
+
+const collect = (text, pattern) => (String(text).match(pattern) ?? []).sort();
+
+/** @returns {{placeholder: string[], icon: string[], commandLink: string[]}} */
+export function markersOf(text) {
+  return {
+    placeholder: collect(text, PATTERNS.placeholder),
+    icon: collect(text, PATTERNS.icon),
+    commandLink: collect(text, PATTERNS.commandLink)
+  };
+}
+
+/**
+ * Compare the markers of an English source string with its translation.
+ * @returns {string[]} names of the marker kinds that differ; empty when compatible
+ */
+export function markerMismatches(source, translated) {
+  if (typeof source !== 'string' || typeof translated !== 'string') return [];
+  const a = markersOf(source);
+  const b = markersOf(translated);
+  return Object.keys(PATTERNS).filter((kind) => a[kind].join('\u0000') !== b[kind].join('\u0000'));
+}
+
+/** True when the translation is safe to ship for the given English source. */
+export const markersMatch = (source, translated) => markerMismatches(source, translated).length === 0;

package/scripts/lib/npm-tooling.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export function nodeScript(file, args = [], options = {}) {
+  const result = spawnSync(process.execPath, [file, ...args], { encoding: 'utf8', windowsHide: true, ...options });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${path.basename(file)} exited ${result.status}\n${result.stdout ?? ''}${result.stderr ?? ''}`);
+  return result;
+}
+
+export function npmCommand(args, options = {}) {
+  const candidates = [process.env.npm_execpath,
+    path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.resolve(path.dirname(process.execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')];
+  const entry = candidates.find((file) => file && fs.existsSync(file));
+  if (!entry) throw new Error('Cannot locate npm-cli.js. Run this check through npm run.');
+  return nodeScript(entry, args, options);
+}

package/scripts/lib/patch-state.mjs

@@ -0,0 +1,304 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const sha256 = (data) => crypto.createHash('sha256').update(data).digest('hex');
+
+export function normalizeInstallPath(installRoot) {
+  const resolved = fs.realpathSync.native(path.resolve(installRoot));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+/** Each installation and application build owns its own record and originals. */
+export function patchStatePaths({ installRoot, dataFolderName, commit, version, home = os.homedir() }) {
+  const normalized = normalizeInstallPath(installRoot);
+  const root = path.join(home, dataFolderName || '.kiro', 'kiro-language-pack');
+  const installDir = path.join(root, 'installs', sha256(normalized));
+  const buildDir = path.join(installDir, 'builds', sha256(JSON.stringify([commit ?? null, version ?? null])));
+  return {
+    installRoot: normalized,
+    root,
+    installDir,
+    buildDir,
+    backupRoot: path.join(buildDir, 'backup'),
+    recordPath: path.join(buildDir, 'patch.json'),
+    reportDir: path.join(buildDir, 'reports'),
+    lockPath: path.join(installDir, 'patch.lock')
+  };
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw new Error(`Cannot read patch state ${file}: ${err.message}`);
+  }
+}
+
+function within(root, rel) {
+  const file = path.resolve(root, rel);
+  const tail = path.relative(root, file);
+  if (!tail || tail === '..' || tail.startsWith(`..${path.sep}`) || path.isAbsolute(tail)) {
+    throw new Error(`Patch path escapes its directory: ${rel}`);
+  }
+  return file;
+}
+
+function currentHash(file) {
+  try {
+    if (!fs.lstatSync(file).isFile()) throw new Error(`Not a regular file: ${file}`);
+    return sha256(fs.readFileSync(file));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/** Write beside the destination, flush, check its contents again, then replace it. */
+export function atomicWrite(file, data, { expectedHash, mode = 0o600 } = {}) {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx', mode);
+    fs.writeFileSync(fd, data);
+    // open() applies umask; an existing application's permissions must survive.
+    fs.fchmodSync(fd, mode);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    if (expectedHash !== undefined && currentHash(file) !== expectedHash) {
+      throw new Error(`File changed outside the patch; left untouched: ${file}`);
+    }
+    fs.renameSync(temporary, file);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+export function writeJsonAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  atomicWrite(file, JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * The journal permits only an original, the last patch, or either side of a pending
+ * write. Originals never change within a build. No rollback writes old bytes over
+ * a third party's edits, and backups are retained even after a successful restore.
+ */
+export class PatchState {
+  constructor({ targetRoot, legacyRecordPath, legacyBackupRoot, legacyVersionField = 'kiroVersion', ...identity }) {
+    this.paths = patchStatePaths(identity);
+    this.identity = {
+      schemaVersion: 2,
+      installRoot: this.paths.installRoot,
+      version: identity.version ?? null,
+      commit: identity.commit ?? null
+    };
+    this.targetRoot = targetRoot;
+    this.legacyRecordPath = legacyRecordPath;
+    this.legacyBackupRoot = legacyBackupRoot;
+    this.legacyVersionField = legacyVersionField;
+    this.snapshots = new Map();
+    this.outputs = new Map();
+    this.load();
+  }
+
+  load() {
+    let record = readJson(this.paths.recordPath);
+    if (record) {
+      if (record.schemaVersion !== 2 || record.installRoot !== this.identity.installRoot
+          || record.commit !== this.identity.commit || record.version !== this.identity.version) {
+        throw new Error(`Patch record belongs to another installation/build: ${this.paths.recordPath}`);
+      }
+    } else if (this.legacyRecordPath) {
+      const legacy = readJson(this.legacyRecordPath);
+      if (legacy && legacy[this.legacyVersionField] === this.identity.version
+          && (!legacy.commit || legacy.commit === this.identity.commit)) {
+        record = {
+          ...legacy,
+          ...this.identity,
+          legacy: { recordPath: this.legacyRecordPath, backupRoot: this.legacyBackupRoot }
+        };
+      }
+    }
+    if (record) {
+      if (!record.files || typeof record.files !== 'object' || Array.isArray(record.files)) {
+        throw new Error('Patch record has no valid file list; keep it for recovery.');
+      }
+      for (const [rel, entry] of Object.entries(record.files)) {
+        within(this.targetRoot, rel);
+        for (const hash of [entry.original, entry.patched, entry.pending?.before, entry.pending?.after]) {
+          if (hash !== undefined && !/^[a-f0-9]{64}$/.test(hash)) throw new Error(`Invalid patch hash for ${rel}`);
+        }
+        if (!entry.original || !entry.patched) throw new Error(`Incomplete patch entry for ${rel}`);
+        entry.backup = `backup/${entry.original}`;
+      }
+    }
+    this.record = record;
+  }
+
+  /** Serialize writers for this install, including writers targeting different builds. */
+  lock() {
+    fs.mkdirSync(this.paths.installDir, { recursive: true });
+    const token = crypto.randomUUID();
+    const owner = { pid: process.pid, token };
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        fs.writeFileSync(this.paths.lockPath, JSON.stringify(owner), { flag: 'wx', mode: 0o600 });
+        break;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+        let other;
+        try { other = readJson(this.paths.lockPath); } catch { /* An interrupted lock write. */ }
+        let alive = true;
+        if (Number.isInteger(other?.pid) && other.pid > 0) {
+          try { process.kill(other.pid, 0); } catch (probe) { if (probe.code === 'ESRCH') alive = false; }
+        } else {
+          alive = Date.now() - fs.statSync(this.paths.lockPath).mtimeMs < 30000;
+        }
+        if (alive || attempt) throw new Error(`Another patch may be running. Retry after it exits: ${this.paths.lockPath}`);
+        fs.rmSync(this.paths.lockPath);
+      }
+    }
+    const release = () => {
+      try {
+        if (readJson(this.paths.lockPath)?.token === token) fs.rmSync(this.paths.lockPath, { force: true });
+      } catch { /* Preserve an unreadable lock instead of removing someone else's. */ }
+    };
+    process.once('exit', release);
+    this.load();
+    return () => { release(); process.removeListener('exit', release); };
+  }
+
+  relative(file) {
+    const rel = path.relative(this.targetRoot, file).split(path.sep).join('/');
+    within(this.targetRoot, rel);
+    return rel;
+  }
+
+  allowed(entry, hash) {
+    return hash !== null && [entry.original, entry.patched, entry.pending?.before, entry.pending?.after].includes(hash);
+  }
+
+  original(rel, entry) {
+    const backup = path.join(this.paths.backupRoot, entry.original);
+    let file = backup;
+    // Legacy copies stay in place. A later retry can still import a repaired backup.
+    if (!fs.existsSync(file) && this.record?.legacy) {
+      if (this.record.legacy.backupRoot !== this.legacyBackupRoot) throw new Error('Unexpected legacy backup directory');
+      file = within(this.legacyBackupRoot, rel);
+    }
+    if (!fs.existsSync(file)) throw new Error(`Backup missing for ${rel}: ${backup}`);
+    const data = fs.readFileSync(file);
+    if (sha256(data) !== entry.original) throw new Error(`Backup hash mismatch for ${rel}: ${file}`);
+    return data;
+  }
+
+  source(file) {
+    const rel = this.relative(file);
+    if (!fs.lstatSync(file).isFile()) throw new Error(`Not a regular file: ${file}`);
+    const before = fs.readFileSync(file);
+    const current = sha256(before);
+    const entry = this.record?.files[rel];
+    if (entry && !this.allowed(entry, current)) throw new Error(`File changed outside the patch; left untouched: ${file}`);
+    const original = entry ? this.original(rel, entry) : before;
+    this.snapshots.set(rel, { file, before, current, original });
+    return original.toString('utf8');
+  }
+
+  stage(file, text) {
+    const rel = this.relative(file);
+    const snapshot = this.snapshots.get(rel);
+    if (!snapshot) throw new Error(`Patch source was not read: ${file}`);
+    const after = Buffer.from(text, 'utf8');
+    if (this.record?.files[rel] || !after.equals(snapshot.before)) {
+      this.outputs.set(rel, { ...snapshot, after });
+    }
+  }
+
+  keepOriginal(data, hash) {
+    const file = path.join(this.paths.backupRoot, hash);
+    if (fs.existsSync(file)) {
+      if (sha256(fs.readFileSync(file)) !== hash) throw new Error(`Backup hash mismatch: ${file}`);
+      return;
+    }
+    fs.mkdirSync(this.paths.backupRoot, { recursive: true });
+    atomicWrite(file, data);
+  }
+
+  save(record) {
+    writeJsonAtomic(this.paths.recordPath, record);
+    this.record = record;
+  }
+
+  importLegacyBackups() {
+    if (!this.record?.legacy) return;
+    for (const [rel, entry] of Object.entries(this.record.files)) {
+      try { this.keepOriginal(this.original(rel, entry), entry.original); }
+      catch { /* Missing/corrupt backups remain recorded for recovery. */ }
+    }
+  }
+
+  apply(metadata) {
+    const files = structuredClone(this.record?.files ?? {});
+    for (const [rel, item] of this.outputs) {
+      if (currentHash(item.file) !== item.current) throw new Error(`File changed while planning: ${item.file}`);
+      const original = sha256(item.original);
+      this.keepOriginal(item.original, original);
+      files[rel] = {
+        original,
+        patched: sha256(item.after),
+        backup: `backup/${original}`,
+        pending: { before: item.current, after: sha256(item.after) }
+      };
+    }
+    this.importLegacyBackups();
+    this.save({ ...this.record, ...this.identity, ...metadata, status: 'applying', files });
+    for (const item of this.outputs.values()) {
+      if (item.after.equals(item.before)) continue;
+      atomicWrite(item.file, item.after, { expectedHash: item.current, mode: fs.statSync(item.file).mode & 0o777 });
+    }
+    const completed = structuredClone(files);
+    for (const rel of this.outputs.keys()) delete completed[rel].pending;
+    this.save({ ...this.record, status: 'patched', files: completed });
+  }
+
+  restore() {
+    if (!this.record) return { restored: 0, problems: [] };
+    const files = structuredClone(this.record.files);
+    const candidates = [];
+    const problems = [];
+    for (const [rel, entry] of Object.entries(files)) {
+      try {
+        const original = this.original(rel, entry);
+        const file = within(this.targetRoot, rel);
+        const current = currentHash(file);
+        if (!this.allowed(entry, current)) throw new Error('file changed outside the patch or is missing; left untouched');
+        candidates.push({ rel, file, original, current });
+        entry.pending = { before: current, after: entry.original };
+      } catch (err) {
+        problems.push(`${rel}: ${err.message}`);
+      }
+    }
+    this.importLegacyBackups();
+    this.save({ ...this.record, status: 'restoring', files });
+    let restored = 0;
+    for (const item of candidates) {
+      try {
+        if (item.current !== files[item.rel].original) {
+          atomicWrite(item.file, item.original, { expectedHash: item.current, mode: fs.statSync(item.file).mode & 0o777 });
+          restored++;
+        }
+        files[item.rel].patched = files[item.rel].original;
+        delete files[item.rel].pending;
+      } catch (err) {
+        problems.push(`${item.rel}: ${err.message}`);
+      }
+    }
+    this.save({ ...this.record, status: problems.length ? 'restore-incomplete' : 'restored', files });
+    return { restored, problems };
+  }
+}

package/scripts/lib/system-locale.mjs

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/** Map an OS language to one of the two translations shipped by this package. */
+export function chineseLocale(language) {
+  const tag = String(language ?? '').trim().split(/[.:@]/)[0].replaceAll('_', '-').toLowerCase();
+  if (tag === 'zh-cht' || tag === 'cht' || /^(tw|hk|mo)$/.test(tag)) return 'zh-tw';
+  if (/(^|-)hans($|-)/.test(tag)) return 'zh-cn';
+  if (/(^|-)hant($|-)/.test(tag) || /(^|-)(tw|hk|mo)($|-)/.test(tag)) return 'zh-tw';
+  return 'zh-cn';
+}
+
+/** Read the display language, rather than inferring it from the time zone. */
+export function systemLocale({ platform = process.platform, env = process.env, run = spawnSync,
+  fallback = () => Intl.DateTimeFormat().resolvedOptions().locale } = {}) {
+  const read = (command, args) => {
+    try {
+      const result = run(command, args, { encoding: 'utf8', timeout: 3000, windowsHide: true });
+      return result.status === 0 ? result.stdout.trim() : '';
+    } catch { return ''; }
+  };
+  if (platform === 'win32') {
+    const shell = env.SystemRoot
+      ? path.join(env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+      : 'powershell.exe';
+    const language = read(shell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '(Get-UICulture).Name']);
+    if (language) return language;
+  } else if (platform === 'darwin') {
+    const languages = read('/usr/bin/defaults', ['read', '-g', 'AppleLanguages']);
+    const first = languages.match(/[a-z]{2,3}(?:[-_][a-z0-9]{2,8})*/i)?.[0];
+    if (first) return first;
+  }
+  for (const key of ['LC_ALL', 'LC_MESSAGES', 'LANGUAGE', 'LANG']) {
+    if (env[key]) return env[key].split(':')[0];
+  }
+  return fallback() || 'en';
+}