dsh-zen-remote 2.3.11 → 2.4.1

package/src/cli/i18n.ts

@@ -0,0 +1,645 @@
+/**
+ * CLI-2 bilingual dictionary and language resolution. Per SPEC the IPC
+ * channel only ever carries machine-readable codes and structured data —
+ * every terminal string the user sees is rendered HERE, on the CLI side, in
+ * the selected language. Placeholder syntax is `{name}`, filled from the
+ * `params` argument.
+ *
+ * Vocabulary discipline (SPEC): the copy speaks ONLY of `host` / `client` /
+ * `peer` — `server` / `both` and similar aliases must not leak into any
+ * string, in either language. The test file scans both tables for the banned
+ * English words to keep it that way.
+ */
+
+export type CliLang = 'zh' | 'en'
+
+export type CliTranslator = ((key: string, params?: Record<string, string | number>) => string) & {
+  /** The language's raw table, for tests and for key inventory checks. */
+  readonly keys: Readonly<Record<string, string>>
+}
+
+const ZH: Readonly<Record<string, string>> = {
+  // ---- help -----------------------------------------------------------------
+  'help.title': 'dsh-zen-remote —— DeepSeek Harness 远程接入命令行',
+  'help.usage': '用法：dsh-zen-remote <命令> [参数]',
+  'help.description': '无需打开浏览器即可完成远程接入配置、设备配对与连接管理。',
+  'help.commands': '命令：',
+  'help.command.setup': 'setup  交互式配置向导（角色、接入方式、配对）',
+  'help.command.status': 'status  查看当前角色、网关与连接状态',
+  'help.command.hostDevice': 'host device pair|list|revoke  host：配对 / 列出 / 吊销接入设备',
+  'help.command.hostIngress': 'host ingress start|stop|verify|snippet  host：管理公网接入',
+  'help.command.clientPair': 'client pair <hostUrl>  client：配对一台远端 host',
+  'help.command.clientUnpair': 'client unpair [<hostUrl>|<entryId>|--all]  client：移除已配对的 host',
+  'help.command.clientList': 'client list  client：列出已配对的 host',
+  'help.options': '参数：',
+  'help.option.lang': '--lang zh|en|auto  界面语言（默认 auto）',
+  'help.option.json': '--json  机器可读 JSON 输出',
+  'help.option.socket': '--socket <path>  指定 IPC socket 路径（默认自动探测）',
+  'help.option.wait': '--wait <seconds>  等待 DSH 启动 / 重载的秒数（默认 20）',
+  'help.option.yes': '--yes, -y  非交互模式：全部采用默认值，绝不挂起等输入',
+  'help.option.noWait': '--no-wait  跳过最后的等待环节（如等待手机完成配对）',
+  'help.option.debug': 'status --debug [outPath]  生成脱敏诊断报告 JSON',
+  'help.option.role': '--role host|client  本机运行角色（peer 尚未启用）',
+  'help.option.profile': '--profile p1,p2  要安装插件的 DSH profile 列表',
+  'help.option.ingress': '--ingress, --mode caddy|cloudflared|external|lan  公网接入方式',
+  'help.option.domain': '--domain <host>  域名',
+  'help.option.cfToken': '--cf-token <token>  Cloudflare API 令牌',
+  'help.option.email': '--email <email>  证书通知邮箱（可选）',
+  'help.option.httpsPort': '--https-port <port>  对外 HTTPS 端口（默认 443）',
+  'help.option.publicUrl': '--public-url <origin>  公网访问地址（https:// 开头）',
+  'help.option.tunnelId': '--tunnel-id <id>  复用已有的 Cloudflare Tunnel ID',
+  'help.option.proxy': '--proxy nginx|caddy|lucky  external 接入的反代类型',
+  'help.option.deviceRole': '--device-role web|desktop-client  待配对的设备类型',
+  'help.option.hostUrl': '--host-url <url>  远端 host 地址',
+  'help.option.code': '--code <8位码>  配对码',
+  'help.option.name': '--name <name>  本机显示名',
+  'help.option.all': '--all  作用于全部（设备 / host 连接）',
+  'help.footer': '提示：不带命令运行即显示本帮助；详见 docs/remote-access.md。',
+
+  // ---- common -----------------------------------------------------------------
+  'common.yes': '是',
+  'common.no': '否',
+  'common.done': '完成',
+  'common.cancel': '取消',
+  'common.retry': '重试',
+  'common.back': '返回',
+
+  // ---- errors & gates -----------------------------------------------------------
+  'err.unknownCommand': '未知命令：{command}。运行 dsh-zen-remote --help 查看全部命令。',
+  'err.role.peerNotEnabled': 'peer 角色尚未启用：CLI 暂不提供 peer 入口，请使用 host 或 client。',
+  'err.role.invalid': '未知角色：{value}（可选 host 或 client；peer 尚未启用）。',
+  'err.roleGate.hostRequired': '此命令需要 host 角色，当前角色是 {role}。请先用 setup 切换角色。',
+  'err.roleGate.clientRequired': '此命令需要 client 角色，当前角色是 {role}。请先用 setup 切换角色。',
+  'err.roleGate.clientCommands': '当前 role 是 {role}，不连接远端 host（可用 dsh-zen-remote setup --role client 切换）。',
+  'err.envShadowed': '字段 {field} 当前被环境变量 {envVar} 遮蔽：请修改该环境变量或启动脚本后再试。',
+  'err.crossUserSocket': '检测到 DSH 以其他系统用户运行，无法访问它的控制 socket：请用同一用户运行本命令，或执行 sudo -E dsh-zen-remote … 重试。',
+  'err.missingOption': '缺少必填参数 --{option}：非交互模式不会挂起等待输入，请补上参数或改在终端交互运行。',
+  'err.desktopProfile': 'desktop profile 由 DeepSeek Harness App 管理，不能通过 CLI 安装插件：{profiles}。',
+  'err.protocolVersion': '本机 DSH 插件的 CLI 协议版本（{found}）与本 CLI（{expected}）不一致：请升级 dsh-zen-remote 插件或 CLI。',
+  'err.notRunning': '未检测到运行中的 DSH 插件：请先启动 DSH（可尝试 dsh --profile {profile} web）再运行本命令。',
+
+  // ---- profile install -----------------------------------------------------------
+  'install.scanning': '正在扫描 <DSH_HOME>/profiles 下的候选 profile …',
+  'install.installed': '已安装插件的 profile：{profiles}',
+  'install.noneInstalled': '尚未在任何 profile 安装 dsh-zen-remote。',
+  'install.selectQuestion': '选择要安装 dsh-zen-remote 的 profile',
+  'install.customEntry': '手动输入其他 profile 名称',
+  'install.running': '正在安装：dsh plugin --profile {profile} add dsh-zen-remote …',
+  'install.failed': '为 {profile} 安装失败（退出码 {code}）。请手动执行：{command}',
+  'install.done': '安装完成：{profiles}',
+
+  // ---- daemon launch --------------------------------------------------------------
+  'launch.found': '检测到运行中的 DSH（角色 {role}，{socketPath}）。',
+  'launch.probing': '未发现运行中的 DSH，尝试拉起系统守护 / 应用 …',
+  'launch.linuxUserUnit': '发现 systemd 用户单元 {unit}，正在启动 …',
+  'launch.linuxSystemUnit': '发现系统级 systemd 单元 {unit}，正在启动 …',
+  'launch.macosService': '发现 launchd 服务 ai.deepseek.dsh.web，正在 kickstart …',
+  'launch.macosApp': '正在启动 DeepSeek Harness 应用 …',
+  'launch.waiting': '等待 DSH 就绪（最多 {seconds} 秒）…',
+  'launch.timeout': '等待 DSH 启动超时（{seconds} 秒）。请确认 DSH 正常启动后重试。',
+  'launch.manual': '无法自动拉起 DSH，请手动启动后重试，例如：\n  dsh --profile {profile} web\n或配置一个 systemd 用户单元（~/.config/systemd/user/dsh-web.service）：\n  [Unit]\n  Description=DeepSeek Harness\n  [Service]\n  ExecStart=dsh --profile {profile} web\n  [Install]\n  WantedBy=default.target\n（macOS 可直接打开 DeepSeek Harness 应用；Windows 请在终端运行 dsh 命令。）',
+
+  // ---- prompts（默认 readline 交互的脚手架文案）-----------------------------------
+  'prompt.defaultLabel': '默认',
+  'prompt.selectOne': '输入序号 [1-{max}]（回车 = {default}）：',
+  'prompt.multiInputPlain': '输入序号（逗号/空格分隔，回车确认默认）：',
+  'prompt.multiInputCustom': '输入序号（逗号/空格分隔，回车确认默认；也可输入 a 手动添加）：',
+  'prompt.customEntryLine': '  a. {entry}',
+  'prompt.customName': 'profile 名称（回车结束）：',
+  'prompt.invalid': '无效输入：{value}',
+  'prompt.requiredEmpty': '此项必填，不能为空。',
+  'prompt.confirmY': '[Y/n]',
+  'prompt.confirmN': '[y/N]',
+
+  // ---- status ----------------------------------------------------------------------
+  'status.role.host': 'host（作为服务端：供手机 / 其他电脑接入）',
+  'status.role.client': 'client（连接远端 host）',
+  'status.role.peer': 'peer（手工设置，未启用）',
+  'status.line.role': '当前角色：{role}',
+  'status.machineName': '本机名称：{name}',
+  'status.pluginVersion': '插件版本：{version}',
+  'status.host.title': 'host 状态：',
+  'status.host.gatewayUp': '网关监听中（端口 {port}）',
+  'status.host.gatewayUpNoPort': '网关监听中',
+  'status.host.gatewayDown': '网关未在监听',
+  'status.host.ingress': '接入方式：{mode}',
+  'status.host.publicUrl': '公开地址：{publicUrl}',
+  'status.host.processCaddy': 'Caddy 进程：{state}',
+  'status.host.processTunnel': 'Cloudflare Tunnel 进程：{state}',
+  'status.process.running': '运行中',
+  'status.process.stopped': '未运行',
+  'status.host.devices': '已配对设备：{count} 台',
+  'status.host.deviceLine': '  · {name}（{deviceRole}）',
+  'status.host.sharedSessions': '已开启远程共享的会话：{count} 个',
+  'status.client.title': 'client 状态：',
+  'status.client.pairedCount': '已配对的 host：{count} / {max} 台',
+  'status.state.revoked': '已吊销',
+  'status.state.incompatible': '版本不兼容',
+  'status.client.compatOk': '接口指纹一致',
+  'status.client.compatDiff': '接口指纹差异 {count} 项',
+  'status.client.compatUnavailable': '接口指纹不可用',
+  'status.client.bridgeCount': '已桥接 {count} 个插件',
+  'status.client.lastError': '上次错误：{error}',
+  'status.debugFailed': '诊断报告获取失败：{error}',
+  'status.debugWriteFailed': '诊断报告写文件失败：{error}',
+  'status.notRunning': '未检测到运行中的 DSH 插件。',
+  'status.paired': '已配对 {count} 台',
+  'status.unpaired': '未配对',
+  'status.online': '在线',
+  'status.offline': '离线',
+  'status.connecting': '连接中',
+  'status.profile': 'profile：{profile}',
+  'status.debugWritten': '诊断报告已写出：{path}',
+
+  // ---- setup wizard ------------------------------------------------------------------
+  'setup.roleQuestion': '选择本机运行角色：',
+  'setup.roleHost': 'host —— 作为服务端运行（开放手机 / 其他电脑连入）',
+  'setup.roleClient': 'client —— 作为客户端运行（连接远端 host）',
+  'setup.switchingToClient': '切换到 client：先停掉托管的 Caddy / Cloudflare 隧道，再写入配置 …',
+  'setup.switchingToHost': '切换到 host：写入配置并等待网关就绪 …',
+  'setup.ingressQuestion': '选择公网接入方式：',
+  'setup.ingressKeep': '保持当前接入配置，直接去验证 / 生成配对码',
+  'setup.ingressCaddy': 'caddy —— 内置 Caddy 自动证书',
+  'setup.ingressCloudflared': 'cloudflared —— Cloudflare Tunnel 内网穿透',
+  'setup.ingressExternal': 'external —— 已有反向代理（Nginx / Caddy / Lucky）',
+  'setup.ingressLan': 'lan —— 局域网 / Tailscale 直连',
+  'setup.domainQuestion': '域名：',
+  'setup.cfTokenQuestion': 'Cloudflare API 令牌：',
+  'setup.emailQuestion': '证书通知邮箱（可留空）：',
+  'setup.httpsPortQuestion': '对外 HTTPS 端口（默认 443）：',
+  'setup.publicUrlQuestion': '公网访问地址（https:// 开头）：',
+  'setup.tunnelConflict': '检测到同名隧道（id {tunnelId}），是否复用？',
+  'setup.verifyTitle': '三灯自检：',
+  'setup.verifyLight1': '第 1 盏：本地网关就绪 —— {state}',
+  'setup.verifyLight2': '第 2 盏：公开地址可达 —— {state}',
+  'setup.verifyLight3': '第 3 盏：真实配对完成 —— {state}',
+  'setup.verifyFailedOptions': '验证未通过：[1] 重试探测  [2] 保留配置退出（稍后用 host ingress verify 重验）',
+  'setup.pairingQr': '用手机浏览器 / 微信扫码，或访问该地址：',
+  'setup.pairingCode': '配对码：{code}（手机 / 浏览器 Web 应用端）',
+  'setup.desktopPairingCode': '桌面客户端配对码：{code}（另一台电脑 DSH 桌面端 / CLI）',
+  'setup.desktopPairingCmd': '另一台电脑终端一键配对：dsh-zen-remote client pair {url} --code {code}',
+  'setup.pairingWait': '等待设备完成配对（手机扫码或另一台电脑桌面端连接均可，Ctrl-C 或 --no-wait 可跳过）…',
+  'setup.pairingDone': '配对完成，三灯全亮。',
+  'setup.pairingSkipped': '已跳过等待；前两灯结果保留，稍后可用 host ingress verify 重验。',
+  'setup.roleSwitchTimeout': '等待角色切换生效超时（{seconds} 秒）：请确认 DSH 正常运行后重试。',
+  'setup.ingressRecommend': '不确定选哪个？回答两个问题帮我推荐',
+  'setup.recommend.publicIp': '是否有公网 IP（或已在路由器做端口映射）？',
+  'setup.recommend.cfDomain': '域名是否托管在 Cloudflare？',
+  'setup.recommend.result': '根据回答推荐：{mode}',
+  'setup.verifyRetry': '重试验证',
+  'setup.verifyKeepExit': '保留配置退出（稍后运行 dsh-zen-remote host ingress verify）',
+  'setup.desktopPairQuestion': '是否顺手生成一个供另一台电脑使用的 desktop-client 配对码？',
+  'setup.clientRepairQuestion': '选择要重新配对的 host：',
+  'setup.summary.title': '配置完成，当前状态：',
+  'setup.summary.role': '角色：{role}',
+  'setup.summary.ingress': '接入方式：{mode} · {publicUrl}',
+  'setup.summary.client': '已配对的 host：{count} / {max} 台',
+  'setup.summary.hint': '提示：dsh-zen-remote status 查看状态；host device pair / client pair 管理配对。',
+  'err.internal': '命令执行失败：{error}',
+
+  // ---- client role ---------------------------------------------------------------------
+  'client.prompt.hostUrl': '远端 host 地址（如 http://10.0.0.2:3080 或 https://tea.example.com）：',
+  'client.prompt.code': '8 位桌面配对码：',
+  'client.prompt.name': '本机显示名（默认 {default}）：',
+  'client.error.urlInvalid': '地址格式无效：请输入如 http://10.0.0.2:3080 或 https://tea.example.com 的完整地址。',
+  'client.error.insecureHttp': '公网地址必须使用 https://（仅内网 / Tailscale / localhost 允许 http://）。',
+  'client.error.codeFormat': '配对码是 8 位字母或数字。',
+  'client.error.nameWriteFailed': '本机显示名写入失败。',
+  'client.error.badCode': '配对码错误或已过期。',
+  'client.error.roleMismatch': '该配对码不是桌面客户端配对码（角色不匹配）。',
+  'client.error.locked': '配对码尝试次数过多，已临时锁定，请约 {seconds} 秒后再试。',
+  'client.error.unreachable': '连不上该 host：请确认地址、网络与防火墙。',
+  'client.error.unexpected': '对端返回了无法识别的应答。',
+  'client.pairedWith': '对端 host：{name}',
+  'clientList.header': '已配对的 host（{count} / {max}）',
+  'clientList.empty': '还没有配对任何 host。',
+  'clientList.fetchFailed': '读取连接状态失败：{error}',
+  'clientUnpair.confirmAll': '确定移除全部 {count} 台已配对的 host？',
+  'clientUnpair.removedAll': '已移除全部 {count} 台已配对的 host。',
+  'clientUnpair.removed': '已移除 {name}。',
+  'clientUnpair.notFound': '没有找到 {target} 对应的已配对 host。',
+  'clientUnpair.missingTarget': '请指定要移除的 host（地址或条目 id），或用 --all 全部移除。',
+  'clientUnpair.selectQuestion': '选择要移除的 host：',
+  'clientUnpair.failed': '移除请求失败。',
+  'client.menuTitle': '已配对的 host：',
+  'client.menuAdd': '新增配对一台 host',
+  'client.menuRepair': '重新配对已有 host',
+  'client.menuRemove': '移除已配对 host',
+  'client.menuDone': '完成退出',
+  'client.limitReached': '已达 8 台上限：请先移除一台，或覆盖重配已有地址。',
+  'client.claiming': '正在兑换配对码并握手 …',
+  'client.claimFailed': '配对失败：{reason}。请重试配对码（已输入的地址保留）。',
+  'client.claimOk': '配对成功，等待连接就绪（最多 10 秒）…',
+  'client.lightCredentials': '本地配对凭证 ✓ —— {state}',
+  'client.lightConnection': 'host 连接 ✓ —— {state}',
+  'client.lightSync': '会话与插件同步 ✓ —— {state}',
+  'client.addAnother': '是否继续添加下一台 host？',
+
+  // ---- host role -----------------------------------------------------------------------
+  'host.device.pairTitle': 'host 设备配对',
+  'host.device.prompt.role': '选择要配对的设备类型：',
+  'host.device.role.web': 'web —— 手机 / 浏览器 Web 应用端',
+  'host.device.role.desktop': 'desktop-client —— 另一台 DSH 桌面客户端',
+  'host.device.error.badRole': '设备类型只能是 web 或 desktop-client：{value} 无效。',
+  'host.device.minting': '正在生成本机配对码 …',
+  'host.device.pairFailed': '配对码生成失败。',
+  'host.device.pairingCode': '配对码：{code}（{minutes} 分钟内有效）',
+  'host.device.noAddress': '未检测到可公开访问的地址：请在浏览器打开网关地址后输入上述配对码完成配对。',
+  'host.device.desktopCommand': '在另一台 DSH 机器的终端运行以下命令完成配对：',
+  'host.device.desktopWizard': '或在网页向导的「设备配对」里输入上述配对码。',
+  'host.device.listTitle': '已配对设备：',
+  'host.device.listEmpty': '还没有已配对的设备。',
+  'host.device.listFailed': '读取设备列表失败：网关未在运行。',
+  'host.device.deviceLine': '  [{id}] {name}（{deviceRole} · {kind}）',
+  'host.device.deviceTiming': '      创建于 {created}，最后活跃 {lastSeen}',
+  'host.device.selectQuestion': '选择要吊销的设备：',
+  'host.device.revokeConfirmAll': '确定吊销全部已配对设备？',
+  'host.device.revokeMissingTarget': '请指定要吊销的设备 id，或用 --all 吊销全部。',
+  'host.device.revoked': '已吊销 {count} 台设备。',
+  'host.device.revokedOne': '已吊销设备 {id}。',
+  'host.device.revokeFailed': '吊销请求失败。',
+  'host.ingress.started': '公网接入已启动（{mode}）。',
+  'host.ingress.stopped': '公网接入已停止。',
+  'host.ingress.confirmStop': '确定停止公网接入（托管的 Caddy / Cloudflare Tunnel 将退出）？',
+  'host.ingress.stopFailed': '停止请求失败。',
+  'host.ingress.error.badMode': '接入方式只能是 caddy、cloudflared、external 或 lan：{value} 无效。',
+  'host.ingress.error.badProxy': '反代类型只能是 nginx、caddy 或 lucky：{value} 无效。',
+  'host.ingress.error.badDomain': '域名格式无效：请输入裸域名（如 tea.example.com）。',
+  'host.ingress.snippetQuestion': '选择要输出的反向代理配置片段：',
+  'host.ingress.snippetTitle': '{proxy} 反向代理配置片段（网关端口 {port}）：',
+  'host.ingress.configWriteFailed': '配置写入失败。',
+  'host.ingress.cfTokenFailed': 'Cloudflare API 令牌保存失败。',
+  'host.ingress.verifyTitle': '验证公开地址 {publicUrl} …',
+  'host.ingress.lightFail': '未通过',
+  'host.ingress.verifySkipped': '已跳过手机配对等待，前两盏灯验证结果已保留。',
+  'host.ingress.verifyCookieInsecure': '反代未正确传递 X-Forwarded-Proto: https：配对 Cookie 缺少 Secure 标记。请在反代配置补上该头后重新验证。',
+  'host.ingress.verifyExpired': '配对码已过期，期间未检测到手机配对：请重新运行 host ingress verify。',
+  'host.ingress.verifyStale': '验证期间接入配置发生变化：请重新运行 host ingress verify。',
+  'host.ingress.verifyReason.noPublicUrl': '未提供公开地址。',
+  'host.ingress.verifyReason.badPublicUrl': '公开地址格式无效。',
+  'host.ingress.verifyReason.runtimeNotReady': '托管入口进程未就绪。',
+  'host.ingress.verifyReason.gatewayUnreachable': '本地网关不可达。',
+  'host.ingress.verifyReason.probeFailed': '公开地址探测未通过：管理面未按预期返回 403（请检查反代是否带 X-Forwarded-* 头）。',
+  'host.ingress.verifyReason.pairRefused': '配对码生成被拒（{detail}）。',
+  'host.ingress.verifyReason.generic': '验证失败（{reason}）。',
+  'host.ingress.caddyError.alreadyRunning': 'Caddy 已在运行，无需重复启动。',
+  'host.ingress.caddyError.missingToken': '缺少 Cloudflare API 令牌：请用 --cf-token 提供，或先在交互模式下输入。',
+  'host.ingress.caddyError.badConfig': 'Caddyfile 生成失败：{detail}',
+  'host.ingress.caddyError.downloadFailed': 'Caddy 下载失败：{detail}（手动安装指引：{installUrl}）',
+  'host.ingress.caddyError.validateFailed': 'Caddy 配置校验失败：{detail}',
+  'host.ingress.caddyError.spawnFailed': 'Caddy 进程启动失败：{detail}',
+  'host.ingress.caddyError.generic': 'Caddy 启动失败（{error}）：{detail}',
+  'host.ingress.tunnelCheckFailed': '域名验证失败（{reason}）。',
+  'host.ingress.tunnelSetupFailed': '隧道创建失败（{reason}）。',
+  'host.ingress.tunnelConflictNonInteractive': '检测到同名隧道（现有 id：{tunnelId}）：非交互模式请用 --tunnel-id {tunnelId} 复用它。',
+  'host.ingress.trustProxyQuestion': '检测到来自 {ip} 的未信任反代来源：把它加入信任列表？',
+  'host.ingress.trustProxyAuto': '检测到未信任反代来源 {ip}，已自动加入信任列表。',
+  'host.ingress.trustProxyDone': '已将 {ip} 加入信任列表。',
+  'host.ingress.trustProxyFailed': '信任列表更新失败。',
+  'host.ingress.lanWaiting': '等待网关在 0.0.0.0 重新就绪（最多 {seconds} 秒）…',
+  'host.ingress.lanTimeout': '等待网关重启超时（{seconds} 秒）：请确认 DSH 正常运行后重试。',
+  'setup.divider': '────────────────────────────────────────────────────────────',
+  'setup.step1Title': '[步骤 1/3] 选择本机运行角色 (host / client)',
+  'setup.step2HostTitle': '[步骤 2/3] 配置 host 接入方式',
+  'setup.step2ClientTitle': '[步骤 2/3] 连接并配对远端 host',
+  'setup.step3HostTitle': '[步骤 3/3] 连通性验证与设备配对',
+  'setup.cfTokenGuide.title': '  Cloudflare API 令牌权限要求（https://dash.cloudflare.com/profile/api-tokens → 创建令牌 →「编辑区域 DNS」模板）：',
+  'setup.cfTokenGuide.caddy': '  • 区域 (Zone) · DNS · 编辑 (Edit) —— 必选（区域资源选「包括 · 特定区域 · 你的域名」）',
+  'setup.cfTokenGuide.tunnel': '  • 区域 (Zone) · DNS · 编辑 (Edit) —— 写入隧道 CNAME 解析记录\n  • 区域 (Zone) · 区域 (Zone) · 读取 (Read) —— 定位域名所属 Zone ID\n  • 账户 (Account) · Cloudflare Tunnel · 编辑 (Edit) —— 创建与配置隧道\n  • 账户 (Account) · 账户设置 (Account Settings) · 读取 (Read) —— 读取账户 ID',
+  'host.ingress.lanPickQuestion': '检测到多个内网 / Tailscale 地址，请选择要使用的访问地址：',
+  'host.ingress.lanPickCustom': '手动输入其他局域网 / Tailscale 地址',
+  'host.ingress.verifyLanProbeWarn': '第 2 盏：公开地址可达 —— 本机自检受限（虚拟网卡 / 路由隔离），已直接生成配对码供外部设备连接验证',
+}
+
+const EN: Readonly<Record<string, string>> = {
+  // ---- help -----------------------------------------------------------------
+  'help.title': 'dsh-zen-remote — DeepSeek Harness remote access command line',
+  'help.usage': 'Usage: dsh-zen-remote <command> [options]',
+  'help.description': 'Configure remote access, pair devices and manage connections without opening the web UI.',
+  'help.commands': 'Commands:',
+  'help.command.setup': 'setup  Interactive setup wizard (role, ingress, pairing)',
+  'help.command.status': 'status  Show the current role, gateway and connection status',
+  'help.command.hostDevice': 'host device pair|list|revoke  host: pair / list / revoke access devices',
+  'help.command.hostIngress': 'host ingress start|stop|verify|snippet  host: manage public ingress',
+  'help.command.clientPair': 'client pair <hostUrl>  client: pair with a remote host',
+  'help.command.clientUnpair': 'client unpair [<hostUrl>|<entryId>|--all]  client: remove a paired host',
+  'help.command.clientList': 'client list  client: list paired hosts',
+  'help.options': 'Options:',
+  'help.option.lang': '--lang zh|en|auto  UI language (default auto)',
+  'help.option.json': '--json  machine-readable JSON output',
+  'help.option.socket': '--socket <path>  explicit IPC socket path (default: auto-discover)',
+  'help.option.wait': '--wait <seconds>  seconds to wait for DSH to start / reload (default 20)',
+  'help.option.yes': '--yes, -y  non-interactive mode: take defaults, never wait for input',
+  'help.option.noWait': '--no-wait  skip the final wait (e.g. waiting for the phone to pair)',
+  'help.option.debug': 'status --debug [outPath]  write the redacted debug report JSON',
+  'help.option.role': '--role host|client  this machine\'s role (peer is not enabled yet)',
+  'help.option.profile': '--profile p1,p2  DSH profiles to install the plugin into',
+  'help.option.ingress': '--ingress, --mode caddy|cloudflared|external|lan  public ingress mode',
+  'help.option.domain': '--domain <host>  domain name',
+  'help.option.cfToken': '--cf-token <token>  Cloudflare API token',
+  'help.option.email': '--email <email>  certificate notification email (optional)',
+  'help.option.httpsPort': '--https-port <port>  public HTTPS port (default 443)',
+  'help.option.publicUrl': '--public-url <origin>  public origin (starts with https://)',
+  'help.option.tunnelId': '--tunnel-id <id>  reuse an existing Cloudflare Tunnel ID',
+  'help.option.proxy': '--proxy nginx|caddy|lucky  reverse-proxy flavor for external ingress',
+  'help.option.deviceRole': '--device-role web|desktop-client  the kind of device to pair',
+  'help.option.hostUrl': '--host-url <url>  remote host address',
+  'help.option.code': '--code <8 digits>  pairing code',
+  'help.option.name': '--name <name>  this machine\'s display name',
+  'help.option.all': '--all  apply to everything (devices / host connections)',
+  'help.footer': 'Hint: running without a command shows this help; see docs/remote-access.md.',
+
+  // ---- common -----------------------------------------------------------------
+  'common.yes': 'yes',
+  'common.no': 'no',
+  'common.done': 'done',
+  'common.cancel': 'cancel',
+  'common.retry': 'retry',
+  'common.back': 'back',
+
+  // ---- errors & gates -----------------------------------------------------------
+  'err.unknownCommand': 'Unknown command: {command}. Run dsh-zen-remote --help for the command list.',
+  'err.role.peerNotEnabled': 'The peer role is not enabled yet: the CLI has no peer entry point — use host or client.',
+  'err.role.invalid': 'Unknown role: {value} (host or client; peer is not enabled yet).',
+  'err.roleGate.hostRequired': 'This command requires the host role; the current role is {role}. Switch roles with setup first.',
+  'err.roleGate.clientRequired': 'This command requires the client role; the current role is {role}. Switch roles with setup first.',
+  'err.roleGate.clientCommands': 'The current role is {role}, which does not connect to a remote host (run dsh-zen-remote setup --role client to switch).',
+  'err.envShadowed': 'The field {field} is shadowed by the environment variable {envVar}: change that variable or your launch script first.',
+  'err.crossUserSocket': 'DSH appears to be running as another system user, so its control socket is not accessible: run this command as the same user, or retry with sudo -E dsh-zen-remote …',
+  'err.missingOption': 'Missing required option --{option}: a non-interactive run never waits for input — pass the option or run interactively in a terminal.',
+  'err.desktopProfile': 'The desktop profile is managed by the DeepSeek Harness app and cannot receive plugins from the CLI: {profiles}.',
+  'err.protocolVersion': 'The local DSH plugin speaks CLI protocol {found} but this CLI speaks {expected}: upgrade the dsh-zen-remote plugin or the CLI.',
+  'err.notRunning': 'No running DSH plugin found: start DSH first (try dsh --profile {profile} web), then run this command again.',
+
+  // ---- profile install -----------------------------------------------------------
+  'install.scanning': 'Scanning candidate profiles under <DSH_HOME>/profiles …',
+  'install.installed': 'Profiles with the plugin installed: {profiles}',
+  'install.noneInstalled': 'dsh-zen-remote is not installed in any profile yet.',
+  'install.selectQuestion': 'Select the profiles to install dsh-zen-remote into',
+  'install.customEntry': 'Type another profile name manually',
+  'install.running': 'Installing: dsh plugin --profile {profile} add dsh-zen-remote …',
+  'install.failed': 'Installing into {profile} failed (exit code {code}). Run it manually: {command}',
+  'install.done': 'Installed into: {profiles}',
+
+  // ---- daemon launch --------------------------------------------------------------
+  'launch.found': 'Found a running DSH (role {role}, {socketPath}).',
+  'launch.probing': 'No running DSH found — trying the system daemon or app …',
+  'launch.linuxUserUnit': 'Found the systemd user unit {unit} — starting it …',
+  'launch.linuxSystemUnit': 'Found the system-level systemd unit {unit} — starting it …',
+  'launch.macosService': 'Found the launchd service ai.deepseek.dsh.web — kickstarting it …',
+  'launch.macosApp': 'Launching the DeepSeek Harness app …',
+  'launch.waiting': 'Waiting for DSH to come up (up to {seconds}s) …',
+  'launch.timeout': 'Timed out waiting for DSH ({seconds}s). Make sure DSH started, then retry.',
+  'launch.manual': 'Could not launch DSH automatically. Start it manually, e.g.:\n  dsh --profile {profile} web\nor create a systemd user unit (~/.config/systemd/user/dsh-web.service):\n  [Unit]\n  Description=DeepSeek Harness\n  [Service]\n  ExecStart=dsh --profile {profile} web\n  [Install]\n  WantedBy=default.target\n(On macOS simply open the DeepSeek Harness app; on Windows run the dsh command in a terminal.)',
+
+  // ---- prompts -----------------------------------------------------------------
+  'prompt.defaultLabel': 'default',
+  'prompt.selectOne': 'Pick 1-{max} (Enter = {default}): ',
+  'prompt.multiInputPlain': 'Pick numbers (comma/space separated; Enter accepts the default): ',
+  'prompt.multiInputCustom': 'Pick numbers (comma/space separated; Enter accepts the default; a to add a name): ',
+  'prompt.customEntryLine': '  a. {entry}',
+  'prompt.customName': 'Profile name (Enter to finish): ',
+  'prompt.invalid': 'Invalid input: {value}',
+  'prompt.requiredEmpty': 'This one is required and cannot be empty.',
+  'prompt.confirmY': '[Y/n]',
+  'prompt.confirmN': '[y/N]',
+
+  // ---- status ----------------------------------------------------------------------
+  'status.role.host': 'host (serves other machines: phones / computers connect in)',
+  'status.role.client': 'client (connects out to a remote host)',
+  'status.role.peer': 'peer (manual config, not enabled)',
+  'status.line.role': 'Current role: {role}',
+  'status.machineName': 'Machine name: {name}',
+  'status.pluginVersion': 'Plugin version: {version}',
+  'status.host.title': 'host status:',
+  'status.host.gatewayUp': 'gateway listening (port {port})',
+  'status.host.gatewayUpNoPort': 'gateway listening',
+  'status.host.gatewayDown': 'gateway not listening',
+  'status.host.ingress': 'Ingress mode: {mode}',
+  'status.host.publicUrl': 'Public address: {publicUrl}',
+  'status.host.processCaddy': 'Caddy process: {state}',
+  'status.host.processTunnel': 'Cloudflare Tunnel process: {state}',
+  'status.process.running': 'running',
+  'status.process.stopped': 'not running',
+  'status.host.devices': 'Paired devices: {count}',
+  'status.host.deviceLine': '  · {name} ({deviceRole})',
+  'status.host.sharedSessions': 'Shared sessions: {count}',
+  'status.client.title': 'client status:',
+  'status.client.pairedCount': 'Paired hosts: {count} / {max}',
+  'status.state.revoked': 'revoked',
+  'status.state.incompatible': 'incompatible',
+  'status.client.compatOk': 'interface fingerprints identical',
+  'status.client.compatDiff': '{count} interface fingerprint difference(s)',
+  'status.client.compatUnavailable': 'interface fingerprints unavailable',
+  'status.client.bridgeCount': '{count} plugin(s) bridged',
+  'status.client.lastError': 'last error: {error}',
+  'status.debugFailed': 'Fetching the debug report failed: {error}',
+  'status.debugWriteFailed': 'Writing the debug report failed: {error}',
+  'status.notRunning': 'No running DSH plugin found.',
+  'status.paired': '{count} paired',
+  'status.unpaired': 'unpaired',
+  'status.online': 'online',
+  'status.offline': 'offline',
+  'status.connecting': 'connecting',
+  'status.profile': 'profile: {profile}',
+  'status.debugWritten': 'Debug report written: {path}',
+
+  // ---- setup wizard ------------------------------------------------------------------
+  'setup.roleQuestion': 'Choose this machine\'s role:',
+  'setup.roleHost': 'host — serve other machines (phones / computers connect in)',
+  'setup.roleClient': 'client — connect out to a remote host',
+  'setup.switchingToClient': 'Switching to client: stopping the managed Caddy / Cloudflare tunnel first, then writing the config …',
+  'setup.switchingToHost': 'Switching to host: writing the config and waiting for the gateway …',
+  'setup.ingressQuestion': 'Choose the public ingress mode:',
+  'setup.ingressKeep': 'Keep the current ingress settings — go straight to verify / pairing',
+  'setup.ingressCaddy': 'caddy — bundled Caddy with automatic certificates',
+  'setup.ingressCloudflared': 'cloudflared — Cloudflare Tunnel',
+  'setup.ingressExternal': 'external — an existing reverse proxy (Nginx / Caddy / Lucky)',
+  'setup.ingressLan': 'lan — LAN / Tailscale direct',
+  'setup.domainQuestion': 'Domain name: ',
+  'setup.cfTokenQuestion': 'Cloudflare API token: ',
+  'setup.emailQuestion': 'Certificate notification email (optional): ',
+  'setup.httpsPortQuestion': 'Public HTTPS port (default 443): ',
+  'setup.publicUrlQuestion': 'Public origin (starts with https://): ',
+  'setup.tunnelConflict': 'A tunnel with this name already exists (id {tunnelId}) — reuse it?',
+  'setup.verifyTitle': 'Three-light check:',
+  'setup.verifyLight1': 'Light 1: local gateway ready — {state}',
+  'setup.verifyLight2': 'Light 2: public address reachable — {state}',
+  'setup.verifyLight3': 'Light 3: a real pairing completed — {state}',
+  'setup.verifyFailedOptions': 'Verification failed: [1] probe again  [2] keep the config and exit (re-verify later with host ingress verify)',
+  'setup.pairingQr': 'Scan with the phone\'s browser, or open this address:',
+  'setup.pairingCode': 'Pairing code: {code} (phone / browser Web app)',
+  'setup.desktopPairingCode': 'Desktop client pairing code: {code} (another computer\'s DSH app / CLI)',
+  'setup.desktopPairingCmd': 'Command on the other computer: dsh-zen-remote client pair {url} --code {code}',
+  'setup.pairingWait': 'Waiting for a device to pair (phone or desktop client; Ctrl-C or --no-wait to skip) …',
+  'setup.pairingDone': 'Paired — all three lights are on.',
+  'setup.pairingSkipped': 'Wait skipped; the first two lights\' results are kept — re-verify later with host ingress verify.',
+  'setup.roleSwitchTimeout': 'Timed out waiting for the role switch to take effect ({seconds}s): make sure DSH is running, then retry.',
+  'setup.ingressRecommend': 'Not sure? Answer two questions and get a recommendation',
+  'setup.recommend.publicIp': 'Do you have a public IP (or a router port forward)?',
+  'setup.recommend.cfDomain': 'Is the domain hosted on Cloudflare?',
+  'setup.recommend.result': 'Recommended from your answers: {mode}',
+  'setup.verifyRetry': 'Retry the verification',
+  'setup.verifyKeepExit': 'Keep the config and exit (re-verify later with dsh-zen-remote host ingress verify)',
+  'setup.desktopPairQuestion': 'Also mint a desktop-client pairing code for another computer?',
+  'setup.clientRepairQuestion': 'Pick the host to re-pair:',
+  'setup.summary.title': 'Setup finished. Current state:',
+  'setup.summary.role': 'Role: {role}',
+  'setup.summary.ingress': 'Ingress: {mode} · {publicUrl}',
+  'setup.summary.client': 'Paired hosts: {count} / {max}',
+  'setup.summary.hint': 'Hint: run dsh-zen-remote status to inspect; pair with host device pair / client pair.',
+  'err.internal': 'The command failed: {error}',
+
+  // ---- client role ---------------------------------------------------------------------
+  'client.prompt.hostUrl': 'Remote host address (e.g. http://10.0.0.2:3080 or https://tea.example.com): ',
+  'client.prompt.code': 'The 8-digit desktop pairing code: ',
+  'client.prompt.name': 'This machine\'s display name (default {default}): ',
+  'client.error.urlInvalid': 'That address does not parse: enter a full origin like http://10.0.0.2:3080 or https://tea.example.com.',
+  'client.error.insecureHttp': 'Public addresses must use https:// (plain http is only allowed on the LAN / Tailscale / localhost).',
+  'client.error.codeFormat': 'The pairing code is 8 letters/digits.',
+  'client.error.nameWriteFailed': 'Writing this machine\'s display name failed.',
+  'client.error.badCode': 'The pairing code is wrong or expired.',
+  'client.error.roleMismatch': 'That code is not a desktop-client pairing code (role mismatch).',
+  'client.error.locked': 'Too many pairing attempts — temporarily locked; retry in about {seconds}s.',
+  'client.error.unreachable': 'The host is unreachable: check the address, network and firewall.',
+  'client.error.unexpected': 'The host answered with an unrecognized response.',
+  'client.pairedWith': 'Connected host: {name}',
+  'clientList.header': 'Paired hosts ({count} / {max})',
+  'clientList.empty': 'No host is paired yet.',
+  'clientList.fetchFailed': 'Reading the connection status failed: {error}',
+  'clientUnpair.confirmAll': 'Remove all {count} paired host(s)?',
+  'clientUnpair.removedAll': 'Removed all {count} paired host(s).',
+  'clientUnpair.removed': 'Removed {name}.',
+  'clientUnpair.notFound': 'No paired host matches {target}.',
+  'clientUnpair.missingTarget': 'Name the host to remove (its address or entry id), or pass --all to remove everything.',
+  'clientUnpair.selectQuestion': 'Pick the host to remove:',
+  'clientUnpair.failed': 'The removal request failed.',
+  'client.menuTitle': 'Paired hosts:',
+  'client.menuAdd': 'Pair a new host',
+  'client.menuRepair': 'Re-pair an existing host',
+  'client.menuRemove': 'Remove a paired host',
+  'client.menuDone': 'Done — exit',
+  'client.limitReached': 'The 8-host limit is reached: remove one first, or re-pair over an existing address.',
+  'client.claiming': 'Redeeming the pairing code and shaking hands …',
+  'client.claimFailed': 'Pairing failed: {reason}. Retry the code (the address you typed is kept).',
+  'client.claimOk': 'Paired — waiting for the connection to settle (up to 10s) …',
+  'client.lightCredentials': 'Local pairing credential ✓ — {state}',
+  'client.lightConnection': 'host connection ✓ — {state}',
+  'client.lightSync': 'Sessions and plugin sync ✓ — {state}',
+  'client.addAnother': 'Add another host?',
+
+  // ---- host role -----------------------------------------------------------------------
+  'host.device.pairTitle': 'host device pairing',
+  'host.device.prompt.role': 'Choose the kind of device to pair:',
+  'host.device.role.web': 'web — a phone / browser web app',
+  'host.device.role.desktop': 'desktop-client — another DSH desktop client',
+  'host.device.error.badRole': 'The device role is web or desktop-client only: {value} is not valid.',
+  'host.device.minting': 'Minting a pairing code …',
+  'host.device.pairFailed': 'Minting the pairing code failed.',
+  'host.device.pairingCode': 'Pairing code: {code} (valid for {minutes} minutes)',
+  'host.device.noAddress': 'No publicly reachable address detected: open the gateway address in a browser and enter the pairing code above.',
+  'host.device.desktopCommand': 'Run this command in a terminal on the other DSH machine:',
+  'host.device.desktopWizard': 'Or enter the pairing code above in the web wizard\'s device-pairing card.',
+  'host.device.listTitle': 'Paired devices:',
+  'host.device.listEmpty': 'No device is paired yet.',
+  'host.device.listFailed': 'Reading the device list failed: the gateway is not running.',
+  'host.device.deviceLine': '  [{id}] {name} ({deviceRole} · {kind})',
+  'host.device.deviceTiming': '      created {created}, last seen {lastSeen}',
+  'host.device.selectQuestion': 'Pick the device to revoke:',
+  'host.device.revokeConfirmAll': 'Revoke ALL paired devices?',
+  'host.device.revokeMissingTarget': 'Name the device id to revoke, or pass --all to revoke everything.',
+  'host.device.revoked': 'Revoked {count} device(s).',
+  'host.device.revokedOne': 'Revoked device {id}.',
+  'host.device.revokeFailed': 'The revocation request failed.',
+  'host.ingress.started': 'Public ingress started ({mode}).',
+  'host.ingress.stopped': 'Public ingress stopped.',
+  'host.ingress.confirmStop': 'Stop public ingress (the managed Caddy / Cloudflare tunnel will exit)?',
+  'host.ingress.stopFailed': 'The stop request failed.',
+  'host.ingress.error.badMode': 'The ingress mode is caddy, cloudflared, external or lan only: {value} is not valid.',
+  'host.ingress.error.badProxy': 'The proxy flavor is nginx, caddy or lucky only: {value} is not valid.',
+  'host.ingress.error.badDomain': 'That domain does not parse: enter a bare hostname (e.g. tea.example.com).',
+  'host.ingress.snippetQuestion': 'Pick the reverse-proxy snippet to print:',
+  'host.ingress.snippetTitle': '{proxy} reverse-proxy snippet (gateway port {port}):',
+  'host.ingress.configWriteFailed': 'Writing the config failed.',
+  'host.ingress.cfTokenFailed': 'Saving the Cloudflare API token failed.',
+  'host.ingress.verifyTitle': 'Verifying the public address {publicUrl} …',
+  'host.ingress.lightFail': 'failed',
+  'host.ingress.verifySkipped': 'Skipped the pairing wait — the first two lights\' results are kept.',
+  'host.ingress.verifyCookieInsecure': 'The reverse proxy does not pass X-Forwarded-Proto: https — the pairing cookie lacks the Secure flag. Fix the proxy header and verify again.',
+  'host.ingress.verifyExpired': 'The pairing code expired with no phone pairing detected — run host ingress verify again.',
+  'host.ingress.verifyStale': 'The ingress config changed during verification — run host ingress verify again.',
+  'host.ingress.verifyReason.noPublicUrl': 'No public address was provided.',
+  'host.ingress.verifyReason.badPublicUrl': 'The public address does not parse.',
+  'host.ingress.verifyReason.runtimeNotReady': 'The managed ingress process is not ready.',
+  'host.ingress.verifyReason.gatewayUnreachable': 'The local gateway is unreachable.',
+  'host.ingress.verifyReason.probeFailed': 'The public-address probe failed: the admin surface did not answer 403 as expected (check the proxy\'s X-Forwarded-* headers).',
+  'host.ingress.verifyReason.pairRefused': 'Minting the pairing code was refused ({detail}).',
+  'host.ingress.verifyReason.generic': 'Verification failed ({reason}).',
+  'host.ingress.caddyError.alreadyRunning': 'Caddy is already running.',
+  'host.ingress.caddyError.missingToken': 'The Cloudflare API token is missing: pass --cf-token, or enter it in an interactive run first.',
+  'host.ingress.caddyError.badConfig': 'Generating the Caddyfile failed: {detail}',
+  'host.ingress.caddyError.downloadFailed': 'Downloading Caddy failed: {detail} (manual install: {installUrl})',
+  'host.ingress.caddyError.validateFailed': 'Validating the Caddyfile failed: {detail}',
+  'host.ingress.caddyError.spawnFailed': 'Starting the Caddy process failed: {detail}',
+  'host.ingress.caddyError.generic': 'Starting Caddy failed ({error}): {detail}',
+  'host.ingress.tunnelCheckFailed': 'The domain check failed ({reason}).',
+  'host.ingress.tunnelSetupFailed': 'Setting up the tunnel failed ({reason}).',
+  'host.ingress.tunnelConflictNonInteractive': 'A tunnel with this name already exists (id {tunnelId}): pass --tunnel-id {tunnelId} in a non-interactive run.',
+  'host.ingress.trustProxyQuestion': 'An untrusted reverse proxy from {ip} was detected: add it to the trust list?',
+  'host.ingress.trustProxyAuto': 'An untrusted reverse proxy from {ip} was detected and added to the trust list automatically.',
+  'host.ingress.trustProxyDone': 'Added {ip} to the trust list.',
+  'host.ingress.trustProxyFailed': 'Updating the trust list failed.',
+  'host.ingress.lanWaiting': 'Waiting for the gateway to come back on 0.0.0.0 (up to {seconds}s) …',
+  'host.ingress.lanTimeout': 'Timed out waiting for the gateway restart ({seconds}s): make sure DSH is running, then retry.',
+  'setup.divider': '────────────────────────────────────────────────────────────',
+  'setup.step1Title': '[Step 1/3] Choose this machine\'s role (host / client)',
+  'setup.step2HostTitle': '[Step 2/3] Configure host ingress',
+  'setup.step2ClientTitle': '[Step 2/3] Pair with a remote host',
+  'setup.step3HostTitle': '[Step 3/3] Connectivity verification & device pairing',
+  'setup.cfTokenGuide.title': '  Cloudflare API token permissions (https://dash.cloudflare.com/profile/api-tokens → Create Token → "Edit zone DNS" template):',
+  'setup.cfTokenGuide.caddy': '  • Zone · DNS · Edit — required (Zone Resources: Include · Specific zone · your domain)',
+  'setup.cfTokenGuide.tunnel': '  • Zone · DNS · Edit — write the tunnel CNAME record\n  • Zone · Zone · Read — locate the domain Zone ID\n  • Account · Cloudflare Tunnel · Edit — create and configure the tunnel\n  • Account · Account Settings · Read — read the Account ID',
+  'host.ingress.lanPickQuestion': 'Multiple LAN / Tailscale addresses detected — pick the address to use:',
+  'host.ingress.lanPickCustom': 'Enter another LAN / Tailscale address manually',
+  'host.ingress.verifyLanProbeWarn': 'Light 2: public address reachable — local self-probe skipped (virtual interface / routing isolation); pairing code minted for direct device verification',
+}
+
+const DICTIONARIES: Readonly<Record<CliLang, Readonly<Record<string, string>>>> = { zh: ZH, en: EN }
+
+/**
+ * Resolve the CLI language: `--lang` wins (`zh` / `en`; `auto` and unknown
+ * values fall through), then `ZEN_REMOTE_LANG`, then the locale variables in
+ * the standard `LC_ALL` > `LC_MESSAGES` > `LANG` order — anything matching
+ * `/^zh/i` is Chinese, everything else (including `C`, `POSIX`, empty) is
+ * English.
+ */
+export function resolveCliLang(flagLang: string | undefined, env?: NodeJS.ProcessEnv): CliLang {
+  const flag = flagLang?.trim().toLowerCase()
+  if (flag === 'zh') return 'zh'
+  if (flag === 'en') return 'en'
+  const vars = env ?? process.env
+  const zen = vars.ZEN_REMOTE_LANG?.trim().toLowerCase()
+  if (zen === 'zh') return 'zh'
+  if (zen === 'en') return 'en'
+  const locale = (vars.LC_ALL || vars.LC_MESSAGES || vars.LANG || '').trim()
+  return /^zh/i.test(locale) ? 'zh' : 'en'
+}
+
+/**
+ * Build a translator for `lang`. Missing keys fall back to the English table
+ * and then to the key itself — a forgotten key must be VISIBLE in the output,
+ * never silently empty.
+ */
+export function createTranslator(lang: CliLang): CliTranslator {
+  const table = DICTIONARIES[lang]
+  const translate = (key: string, params?: Record<string, string | number>): string => {
+    let text = table[key] ?? DICTIONARIES.en[key] ?? key
+    if (params !== undefined) {
+      for (const [name, value] of Object.entries(params)) {
+        text = text.replaceAll(`{${name}}`, String(value))
+      }
+    }
+    return text
+  }
+  return Object.assign(translate, { keys: table })
+}