Repository navigation
Description
想解决什么问题
插件集 6 个带客户端的插件(dsh-idle-archive / dsh-lan-proxy / dsh-mcp-manager / dsh-notifier / dsh-provider-usage / dsh-web-file-preview)的浏览器端 UI 文案全部硬编码中文,无任何多语言能力。上游 dsh v0.1.2-alpha.1 已发布官方多语言框架(release「支持注册第三方语言,并补全多语言文本」,包 @deepseek-ai/dsh-client-locale),插件集应复用该框架统一接入,避免各插件各自为政、也避免自造 i18n 轮子。
本 issue 是方案评审入口:涉及 catalog 新增官方类型依赖(红线),方案获批(approved)前不实施。调研基于 dsh v0.1.2-alpha.1 源码(
packages/client/locale与ui-slots、两篇架构笔记、verify-client-ui-i18n门禁)逐文件核实。
调研结论(v0.1.2-alpha.1 官方框架能力)
| 能力 | 机制 |
|---|---|
| 语言偏好 | 设置 → 通用「语言」行;loopback 持久化 settings.yaml: locale.preference;浏览器 navigator.languages 初始匹配,en 兜底 |
| 字典注册 | ctx.locale.register(ns, {zh,en}) typed 形式,编译期强制 zh/en 键完整对齐;另有 register(ns, localeId, dict) 单语言 untyped 形式供语言包 |
| 类型化命名空间 | declare module '@deepseek-ai/dsh-client-ui-slots' 合并 LocaleNamespaceMap,每插件一 ns |
| 翻译消费 | t seat:slots.register(..., locale: NS) → 渲染器按 (ns, revision) 注入类型化 t,切语言自动重渲染;或 ctx.locale.bind(ns) 显式调用;{name} 模板插值 |
| 第三方语言 | ctx.locale.addLanguage({id, label, fallback})——BCP47 校验、fallback 链终止于 en、防环、与字典可乱序注册(v0.1.2-alpha.1 现成能力) |
| 查找链 | 活动语言 fallback 链 → common 共享命名空间 → key 本身 |
| 刷新机制 | revision 单调递增 + getSnapshot/subscribe;locale/change 仅切换时发(防 boot 风暴);注册期 label 走 thunk 零重注册 |
| 官方原则 | 用户/模型/提供方/wire 文本与协议 token 是数据不翻译;日期/时长模板进字典(弃 Intl);派生层返回结构化值由渲染组合 |
期望的方案
总原则:复用 @deepseek-ai/dsh-client-locale,绝不自造 i18n 轮子;宿主端稳定标识/数据不翻译,仅产品化 UI 文案进字典;语言偏好读写一律经官方服务,禁自造 localStorage key。
每插件落地形态(照官方 ui-settings-plugin-inventory 样板):
- 新增
src/client/locales.ts:zh(key 源)+en satisfies keyof typeof zh锁双语平衡; declare module合并LocaleNamespaceMap(每插件一 ns,如'settings.mcp');inject数组加'locale';apply 内ctx.effect(() => ctx.locale.register(NS, {zh,en}));- 翻译消费双通道明确分工:
- React slots 组件:props 收
{t}、register 带locale: NS、label 用 thunk; - 原生 DOM 渲染(浮动面板/胶囊/toast):
ctx.locale.bind(NS)+locale.subscribe按 revision 重绘(防重入、ctx.effect回收);
- React slots 组件:props 收
- 禁止向
common注册;模板参数名限\w+;禁止t()结果拼innerHTML。
notifier 边界(固定内容双语、动态内容不翻译):
- 通知类型(
NOTIFY_KINDSkind)走客户端字典——只存/只推稳定 kind 标记,渲染期翻译,切语言后历史通知类型随之变化; - 会话名/文件名/错误 details/时间值等动态数据原样呈现;
toast.ps1系统通知不经浏览器 locale,固定文案现状保留、文档明示边界;- 耗时/单位格式模板(「45 秒」「N 个工具」)进字典模板(弃 Intl),formatter 收
t。
门禁:官方 verify-client-ui-i18n 对仓库形态(.ts + createElement/el({text}))检测失效(已核实),照官方思想自研轻量 AST 检查进 CI(拒绝 JSX/createElement 字符串参数/text: 属性/textContent= 中的自然语言文案;豁免注释、字典文件、token),另加「全插件 ns 无交集」断言。
分阶段
- P1 样板 dsh-mcp-manager(React 卡 + 原生 DOM 面板双路并存,一次压测两通道):types 注入 + 组件签名改造 + inject 加 locale + 原生 DOM 订阅重绘 + zh/en 切换浏览器实测(浮窗/面板/设置卡三面断言)+ 构建产物无
@deepseek-ai运行时 require 断言 + AST 门禁上线 + 语言包接入模板文档; - P2 推广:idle-archive → lan-proxy → notifier(含通知 kind 标记化)→ provider-usage;web-file-preview 文案基线去注释重估后单列;
- P3:ja 等语言包落地(另立 issue);历史数据(
history.jsonl已渲染内容)不随语言变,文档明示。
红线与依赖
- catalog 新增
@deepseek-ai/dsh-client-locale/@deepseek-ai/dsh-client-ui-slots(0.1.2-alpha.1,仅 import type,编译期擦除、不违反运行时零依赖纪律); - 与 适配上游 dsh 0.1.2-alpha.1:dsh-client-runtime / APIProxy 移除,受影响包适配清单 #323(dsh-client-runtime / APIProxy 移除适配)相关联,dsh 本体升级评估合并一次审批;
- 本方案属新增依赖 + 公共 API 行为(客户端组件签名)变更,需维护者 approved 后实施。
补充说明
- 已做过独立子 agent 对抗评审(正确性/边界、性能、安全、可维护性、兼容性、仓库纪律、分阶段 DoD、遗漏项、备选路径),本方案为过滤后定稿;
- 英文文案维护负担(随 UI 改动双倍涨、需维护「官方 common 已有词对照表」防重复定义)在 P1 文档中一并约定;
- 相关既有 issue:适配上游 dsh 0.1.2-alpha.1:dsh-client-runtime / APIProxy 移除,受影响包适配清单 #323(dsh 0.1.2-alpha.1 适配)。
Activity
liyangbing commentedon Aug 30, 2026
The proposed split between typed slot translations and an explicitly subscribed DOM surface is a useful boundary. I would add one release-gate artifact before P1 approval: a generated namespace/key manifest per plugin, checked against the built client bundle.
The gate should prove, for each pinned alpha.1 host:
zhkey has anenkey with the same interpolation names;common;bind/subscribepaths are disposed on plugin unload;For the notifier case, retaining stable
kindvalues and translating only at render time also preserves machine-readable history. The receipt should distinguish translated UI assertions from unchanged dynamic values and system-toast behavior. That keeps the alpha.1 capability claim narrow and makes a failed locale switch diagnosable rather than a generic plugin failure.The independent handbook has a related plugin audit boundary—declared runtime compatibility should be backed by a pinned behavior matrix, not only a successful build: community plugin audit.
wingsky-1 commentedon Aug 31, 2026
维护者授权留痕(2026-08-31)
维护者在本会话口头指示「i18n 可以做了」——Phase 3 授权启动(i18n 插件集落地)。
红线提示:本 issue 涉及 catalog 新增官方类型依赖(
dsh-client-locale),按仓库红线approved标签永不代打。请在方便时亲手补打approved标签(或确认本评论即视为方案批准);在此之前 Agent 将先做纯只读的机制核实(评审 P0-5:t seat 真实机制——slots.register的 locale 参数 vsctx.slots.installLocale,对照官方ui-settings-plugin-inventory样板),确认后再动 catalog 与代码。首批落地对象:idle-archive / lan-proxy / mcp-manager / notifier / provider-usage / web-file-preview(6 个客户端包)。
docs: 适配计划 Phase 3 机制核实结论——官方 t seat 为 slots.register locale 参数 + Loc…
wingsky-1 commentedon Aug 31, 2026
维护者授权确认(2026-08-31,口头授权视为批准)
维护者在本会话明确选择「口头授权视为批准,直接开工」——Phase 3 i18n 落地正式启动(不再等 approved 标签;本评论 + 前述授权留痕(issue-comment-5474320874)即为批准依据)。
落地将按计划执行:catalog 新增官方类型依赖(
dsh-client-locale等)→ 6 包locales.ts+LocaleNamespaceMap合并 +inject locale+ 双通道翻译消费 → 每段全门禁 + 阶段 commit。第一批试点 1-2 个包,机制验证后再铺开。wingsky-1 commentedon Aug 31, 2026
Phase 3 P0 卡点解决:TS2664 根因 + 试点落地(commit 8979268)
根因(与 TS 版本无关,是上游发布物类型面缺陷)
@deepseek-ai/[email protected]发布物lib/types/*.d.ts的相对导入保留了.ts后缀:index.d.ts:import type { HostObservable } from './renderer.ts'、export * from './store.ts'、export * from './renderer.ts'renderer.d.ts反向from './index.ts'.d.ts(无.ts)declare module增强的模块名解析与普通 import 走不同路径(不共享 import 建立的解析缓存),该缺陷导致 augmentation 判TS2664 cannot be found。TS 5.9.3 / 6.0.3 / 7.0.2 三版本实测行为一致(TS 6.0.3 更严格,连普通 import 都报 TS2307),故换 TS 版本不可解。现象与 microsoft/TypeScript#63960(augmentation 解析顺序依赖)同类。Workaround(已落地,上游修复后可删)
在
declare module前显式import type { LocaleNamespaceMap } from '@deepseek-ai/dsh-client-ui-slots',把包拉进解析图即通过;连续 3 次 build 稳定复验。已加注释说明原因与移除条件。官方推荐用法核实
ui-jobs同款模式:import { zh, en, NS, type Key } from './locales.ts'+declare module '@deepseek-ai/dsh-client-ui-slots'+ctx.effect(() => ctx.locale.register(NS, { zh, en }))dsh-client-localeREADME:ctx.locale.register(ns, {zh,en})注册、ctx.locale.bind(ns)/ 框架tseat 翻译、UI 挂载后注册字典免重载试点验收(dsh-idle-archive)
src/client/locales.ts:zh key 源 + en 全键对齐(Record<Key, string>编译期锁平衡),覆盖弹窗/设置卡/toast 全文案ctx.locale.register/bind(原生 DOM)+slots.register({ locale: NS })(Reacttseat)+ 语言切换 subscribe 重绑重绘ui-slots(显式 import type + declare module)与store(ui-slots 类型面传递依赖);dsh-client-locale类型包未 import 不引入tsconfig.json+rewriteRelativeImportExtensions(./locales.ts后缀 emit 改写)8979268下一步
按试点样板铺开其余 5 包(lan-proxy / mcp-manager / notifier / provider-usage / web-file-preview);notifier 边界维持既定:kind 走客户端字典、动态数据原样、
toast.ps1固定文案保留并文档明示。feat(dsh-idle-archive): i18n 试点——双语字典 + 官方 locale 双通道接入(#348)
feat(dsh-lan-proxy): i18n 接入——设置卡双语字典 + 官方 locale 双通道(#348)
feat(dsh-provider-usage): i18n 接入——胶囊/面板/设置 tab 三面双语(#348)
feat(dsh-mcp-manager): i18n 接入——浮窗/面板/表单/设置卡四区双语(#348)
feat(dsh-web-file-preview): i18n 接入——预览 Modal/灯箱/错误态双语(#348)
feat(dsh-notifier): i18n 接入——设置卡/历史列表/权限降级说明双语(#348)
wingsky-1 commentedon Aug 31, 2026
Phase 3 完成:6 包 i18n 全量落地(commit 8979268..4688eb8,已推送 origin/0.2.0)
P0 卡点解决(试点,8979268)
declare module增强报 TS2664 的根因是上游发布物类型面缺陷:@deepseek-ai/[email protected]的lib/types/*.d.ts相对导入保留.ts后缀(from './renderer.ts',磁盘只有.d.ts),augmentation 的模块名解析(与普通 import 不同路径、不共享解析缓存)判 cannot be found。TS 5.9.3 / 6.0.3 / 7.0.2 三版本实测一致,与 TS 版本无关。Workaround:declare module前显式import type { LocaleNamespaceMap } from '@deepseek-ai/dsh-client-ui-slots'把包拉进解析图(microsoft/TypeScript#63960 同类顺序依赖),6 包统一采用并注释移除条件——上游修复发布物后可整体删除。铺开模式(5 包,fb62448/d6dcaf6/1e308b6/f027c67/4688eb8)
src/client/locales.ts:zh key 源 + en 全键对齐(编译期锁平衡),覆盖设置卡/浮窗/面板/表单/错误态全部用户可见文案ctx.locale.register(NS, {zh,en})+locale.bind(原生 DOM)/slots.register locale: NS(React t seat);语言切换 subscribe 重绑var t;多文件包(provider-usage / mcp-manager / web-file-preview)用src/client/i18n.ts共享 t 活绑定(export let+bindLocale)t()(模块加载时 t 未装配,不能固化文案)providerBadgeText/fullscreenLabel加可选 t 参数(缺省中文不变),宿主 bundle 不引入 client 字典saved.indexOf("失败")、notifiersaved.indexOf("失败")||"不可用"改 msg+err 状态(英文态下字符串匹配必失效){PROVIDER}字面占位样式经参数传值保持原文视觉(官方插值单遍替换、缺失参数保留原样,已核实实现)toast.ps1固定文案(按既定拍板保留)、未知 kind 等动态数据验收
build/test/contract/pack:check全绿(两轮:试点后、铺开后)dsh-client-ui-slots(类型面)+dsh-client-store(ui-slots 类型传递依赖)入 devDeps,dsh-client-locale类型包未使用不引入(catalog 同步清理)后续建议
lib/types/*.d.ts的.ts后缀相对导入后,6 包可统一删除显式import typeworkaround(各文件均有注释标记)docs(dsh-lan-proxy): 归档 i18n 隔离实测截图——双语设置卡 + 3082 改端口热更新(#348)
feat: 0.1.2-alpha.2 适配 + 六包 i18n 接入(#323 #348)