繁中界面转换 linmino/dsh-zh-tw-ui

dsh-zh-tw-ui

把整个 DeepSeek Harness（DSH）Web UI 渲染成繁体中文（台湾）——包括 DSH 自己的文案、第三方插件文案，以及后续 DSH 版本新增的文字——做法是转换 DOM，而不是发布语言包。

Settings -> General -> Language: 中文 (Simplified) <- the app's own locale
What you actually see: 繁體中文（台灣） <- converted on screen

因为工作在渲染层，它没有基于词典的语言包那种失败模式：没覆盖到的文案会退回简体中文，UI 看起来只翻译了一半。

问题

DSH 只带两个语言区域：zh（简体）和 en。在台湾用 DSH，会同时踩到三个坑：

1. DSH 自己的 UI 是简体，没有语言包可用；
2. 第三方插件（市场、侧边栏、IM 桥接、Agent Teams……）各自带自己的简体词典，任何语言包都够不到；
3. DSH 每次发版都会新增文案，所以语言包的词典永远落后一个版本。

这个插件直击共同的根因：不管文字是谁产生的，都在屏幕上转换。

目标 / 非目标

目标

| G1 | 整页都是繁体中文：DSH 本身、第三方插件，以及之后出现的动态内容 |
| G2 | 与 DSH 版本解耦——DSH 升级不能把它弄坏 |
| G3 | 不碰 DSH 内部：不注册词典、不打 LocaleRuntime 补丁、不依赖 @deepseek-ai/ peer 范围——所以 DSH 的兼容性闸门永远不会跳过它，它也能和其他语言区域插件共存 |
| G4 | 安全边界清晰：代码、编辑器，以及你输入的任何东西都绝不改动 |
| G5 | 可回退、可审计、可调（运行时开关、覆盖表、跳过标记） |

非目标

- 不是语言包：DSH 的 Language 列表里不加新条目，也不改 DSH 的语言区域设置。
- 不做简体 → 繁体之外的翻译：英文原样保留，不调用模型。
- 不改存储的数据——见限制。
- 只支持 Web / 桌面客户端：TUI 或无头配置档里没有 DOM。
- 不转换画进 canvas 的文字，也不碰跨域 iframe。

为什么不直接用另一个繁体中文插件？

这正是项目存在的原因，所以这里说点实话。所有数据都在 2026-10-13 从各包的 npm manifest 或仓库 README 核对过。

| 方案 | 机制 | 覆盖第三方插件 | 与 DSH 0.2.0-rc.2 的关系 |
| @huanlin/dsh-plugin-better-locale 0.4.3 | 注册词典（39 个命名空间） | 否 | peer 写的是 ^0.1.5-rc.2（排除 0.2.x）→ 需要手动精确版本豁免才能加载 |
| @mimateinn/dsh-i18n 0.2.6 | 词典 + 简体→繁体字符回退 | 是 | peer 写的是 <0.2.0-0 → 没有豁免就被兼容性闸门拦下 |
| dsh-locale-zh-tw（npm，0.1.1） | 给 LocaleRuntime 内部打补丁 | 是 | 按 dsh-client-locale@0.1.1-rc.2 的结构自我描述；版本不匹配时静默降级 |
| dsh-multi-lang-ui 0.1.1 | 词典 + 字符表 + DOM 兜底 | 是 | peer 没有上限，能过闸——机制上最接近本项目 |
| iceice666/dsh-locale-zh-tw | 只有词典（50 ns / 1691 条字符串） | 否（按其 README 的设计如此） | — |
| dsh-zh-tw-ui（本项目） | 纯 DOM 转换 | 是 | 无 peer 依赖，不碰任何 DSH API |

现有几种做法各有结构性弱点：

1. 基于词典（better-locale、iceice666）——覆盖范围冻结在打包时对应的上游版本。在本机实测：better-locale 0.4.3 带 39 个命名空间，而 DSH 0.2.0-rc.2 注册了约 49 个核心命名空间，其中 17 个完全没有繁体词典（pluginManager、permission、settings.shell、settings.webSearch、agent-team、voice-input、schedule.manager……）。更糟的是，它的回退链是 zh-TW → zh → en，所以这些缺口会渲染成简体，而不是英文——这正是语言包看起来「装了但没反应」的原因。
2. 改核心（npm 上的 dsh-locale-zh-tw）——与 DSH 内部实现紧耦合，而且有意设计成静默降级：DSH 更新之后，它可能干脆什么都不做，也不报错。
3. 声明 peer 范围——你的 DSH 版本落在范围外时，DSH 会在启动时跳过整个 bundle，悄无声息（磁盘上的 compatibility.json 豁免列表，就是绕开这一点的痕迹）。

本项目的取舍：不碰任何 DSH API，只在 DOM 上干活。代价是它属于显示层转换；换来的是版本无关、能覆盖第三方插件，以及看得见的失败。完整后果列在限制一节。

注意：dsh-multi-lang-ui 在功能上与本项目重叠，是个可行的替代方案。本项目有意做得更小、更单一：只做 DOM 转换——只干一件事，没有词典要同步，也不依赖任何 @deepseek-ai/。

工作原理

┌─ DSH 自己的文案（简体）屏幕文本 ───────┼─ 第三方插件的文案（它们自己的简体） └─ 稍后才出现的内容（流式输出、动态面板） │ ▼ DOM 文本节点 → OpenCC cn→twp（台湾用词）→ 覆盖表 → 写回 ▲ └─ MutationObserver：节点新增 / 文本变化时重跑

- 引擎：OpenCC cn → twp（简体 → 繁体，并用台湾词汇）：设置→設定，网络→網路，软件→軟體，文件夹→資料夾，服务器→伺服器，内存→記憶體，屏幕→螢幕，鼠标→滑鼠，保存→儲存，搜索→搜尋，插件→外掛。
- 一张小的覆盖表（src/convert.mjs 里的 DEFAULT_OVERRIDES）用来修正用词 OpenCC 会漏掉一些词，或者转成非台湾用法：只讀→唯讀、超時→逾時、反饋→回饋、獲取→取得、許可權→權限。
- 设为 zh-Hant-TW，浏览器就会选用台湾字形。
- 按文本节点做记忆化，不含汉字的字符串直接短路返回，只有值真的变了才写入——转换器还会记住自己写过的内容，所以永远不会和 React 来回打架。

安全边界：哪些内容永不转换

| 目标 | 行为 |
| 、CodeMirror / Monaco / xterm / ace / 语法高亮 | 子树与属性都不动 |
| | 只处理 placeholder / title；你输入或选择的内容不动 |
| contenteditable（包括富文本编辑器） | 不动 |
| <math>、 | 不动 |
| 任何标了 data-zh-tw-skip 或 translate="no" 的内容 | 不动 |
| 不含汉字的字符串（英文、假名、数字、代码） | 原样放过 |

换句话说：代码永远不会被改写，复制代码的行为和以前完全一样。

安装

A. 从本仓库安装（目前支持的方式）

git clone https://github.com/linmino/dsh-zh-tw-ui.git
cd dsh-zh-tw-ui
node install.mjs --profile desktop # 'desktop' 是默认值；web 配置档请用 --profile web

install.mjs 只做四件事，全部可回退：

1. 把配置档的 package.json 和 cordis.patch.yml 备份为 *.zh-tw-ui.bak；
2. 把 dsh-zh-tw-ui 追加到 dsh.profile.bundles；
3. 把 locale 那一行的 preference 设为 zh（底层是简体，屏幕上是繁体——这样即使你之后移除别的语言包，界面也仍是中文，而不会退回英文、没东西可转）；
4. 建立链接 <profile>/node_modules/dsh-zh-tw-ui → 本目录。

它不跑任何包管理器，所以配置档里其他东西不会被重新解析。

然后重启 DeepSeek Harness——新 bundle 只在启动时组装，刷新页面不够。

B. 从 npm 安装（尚未发布）

dsh-zh-tw-ui 这个名字目前在 npm 上还没人占用。发布之后：

dsh plugin --profile desktop add dsh-zh-tw-ui

卸载

node uninstall.mjs --profile desktop

删掉链接、移除 bundle 条目，并还原两份备份。你的插件源码永远不会被删除。之后重启 DSH。

使用

插件没有界面，也不需要配置。要调它，用主窗口的 DevTools 控制台：

__dshZhTw.status() // { version, enabled, textNodes, attributes, skippedSubtrees, passes }
__dshZhTw.off() // stop converting (text already converted stays)
__dshZhTw.on() // resume
__dshZhTw.toggle()
__dshZhTw.refresh() // full re-scan
__dshZhTw.convert('设置') // test one string -> '設定'

开关状态存在 localStorage['dsh-zh-tw-ui:enabled']。
改措辞：编辑 src/convert.mjs 里的 DEFAULT_OVERRIDES（一个 [simplified, traditional] 对的列表），运行 node build.mjs，刷新页面。

排除某个区域：给元素加上 data-zh-tw-skip（对照参考或截图时很方便）。

限制

一份诚实的清单。以下问题都源自显示层的设计：

1. 屏幕变了，数据没变。 存储的文本、模型收到的内容、写入文件的内容都保持原样。
- 复制代码：不受影响（代码块已排除）。
- 复制正文：你会得到繁体，因为复制的内容来自屏幕。
- 你自己的消息气泡以繁体渲染，但模型收到的仍然是你输入的原文。
2. 画进 canvas 的文字不会转换（图表、图片编辑器、自绘组件）。
3. 跨域 iframe 内容不会转换（同源 iframe 会）。
4. 措辞可能不符合上下文。 OpenCC 是短语表，偶尔会出错（尤其是专有名词）。调整覆盖表，或用 data-zh-tw-skip 标记该区域。
5. 有性能开销。 每个文本节点都要查一次词典。记忆化、非汉字短路，以及只处理新增/变化的节点，把这些开销压得很小，但很长的对话或巨大的列表页可能会有轻微延迟。
6. 它不是语言包。 DSH 的 Language 列表里不会出现「繁體中文」条目。如果你把 DSH 切到英文，屏幕上就没有中文可转换，效果就是「什么都没发生」。
7. 仅限 Web/桌面客户端 —— TUI 和无头模式没有 DOM。
8. 链接式安装可能被清除。 如果之后从市场安装另一个插件，触发 pnpm 重新解析 node_modules，链接可能消失（插件停止工作；DSH 本身不受影响）。重新运行 node install.mjs。
9. 原生界面不在范围内：DSH Desktop 的原生菜单、托盘，以及其他非 Web UI。

测试

npm install
npm test

14 项测试，覆盖：

- 转换质量（核心词汇、台湾覆盖表）、非汉字透传、二次遍历下的稳定性；
- 跳过规则：code/pre/textarea/input/contenteditable/CodeMirror/Monaco/ svg/data-zh-tw-skip/translate="no"，以及表单控件只转换其 placeholder；
- 属性转换（title/placeholder/aria-label/alt）；
- 实时变更、流式更新，以及稳定后不再写入（不与 React 来回拉锯）；
- off() 停止，on() 补上错过的内容；
- 端到端：生成的 lib/client.js 通过 DSH 真实的
window.__ModuleLoader__.load(...) 协议加载，应用到 DOM，包括运行时开关和持久化；
- 没有 DOM 时 apply() 永不抛错（它绝不会弄坏客户端）。

仓库结构

build.mjs generates lib/client.js from src/ (with a syntax check)
install.mjs 安装到配置档（备份、打包、语言区域、链接） uninstall.mjs 还原 lib/index.js 宿主部分：空操作 lib/client.js 生成的浏览器包（DSH 唯一加载的文件） src/apply.mjs cordis 客户端插件主体（开关、运行时 API） src/convert.mjs 转换引擎 + 台湾用词覆盖表 src/dom-convert.mjs DOM 遍历、跳过规则、MutationObserver src/vendor/ 内置的 opencc-js（字节级一致，附带许可证） cordis.patch.yml 把插件行插入 DSH 的补丁层 test/run.mjs 测试套件

许可证

本项目采用 MIT（见 LICENSE）。它内嵌 opencc-js（MIT）和 OpenCC 词典（Apache-2.0）——文件哈希与完整许可证文本见 THIRD-PARTY-NOTICES.md。

致谢

- opencc-js —— 浏览器里的 OpenCC
- OpenCC —— 简体/繁体与台湾用词词典
- 还有每一位受够了简体界面、动手写插件的人