Skip to content

[feature] [meta] 插件集多语言(i18n)能力:复用上游 dsh-client-locale 框架(dsh v0.1.2-alpha.1 基线) #348

Closed

Description

@wingsky-1

想解决什么问题

插件集 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 样板):

  1. 新增 src/client/locales.ts:zh(key 源)+ en satisfies keyof typeof zh 锁双语平衡;
  2. declare module 合并 LocaleNamespaceMap(每插件一 ns,如 'settings.mcp');
  3. inject 数组加 'locale';apply 内 ctx.effect(() => ctx.locale.register(NS, {zh,en}));
  4. 翻译消费双通道明确分工:
    • React slots 组件:props 收 {t}、register 带 locale: NS、label 用 thunk;
    • 原生 DOM 渲染(浮动面板/胶囊/toast):ctx.locale.bind(NS) + locale.subscribe 按 revision 重绘(防重入、ctx.effect 回收);
  5. 禁止向 common 注册;模板参数名限 \w+;禁止 t() 结果拼 innerHTML。

notifier 边界(固定内容双语、动态内容不翻译):

  • 通知类型(NOTIFY_KINDS kind)走客户端字典——只存/只推稳定 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 已渲染内容)不随语言变,文档明示。

红线与依赖

补充说明

Activity

  1. added
    enhancementNew feature or request
    needs-proposal-review需要维护者评审方案后再决定是否推进(在原 issue 讨论,不单开决策 issue)
    on Aug 30, 2026
  2. pinned this issue on Aug 30, 2026
  3. liyangbing commented on Aug 30, 2026

    @liyangbing

    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:

    • every zh key has an en key with the same interpolation names;
    • each namespace is owned by exactly one plugin and does not silently extend common;
    • slot registration and DOM bind/subscribe paths are disposed on plugin unload;
    • a locale switch after a cold boot and after an existing Session is open produces one bounded revision update, without duplicating listeners;
    • the emitted browser artifact contains no runtime import of the locale package when the dependency is type-only.

    For the notifier case, retaining stable kind values 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.

  4. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    维护者授权留痕(2026-08-31)

    维护者在本会话口头指示「i18n 可以做了」——Phase 3 授权启动(i18n 插件集落地)。

    红线提示:本 issue 涉及 catalog 新增官方类型依赖(dsh-client-locale),按仓库红线 approved 标签永不代打。请在方便时亲手补打 approved 标签(或确认本评论即视为方案批准);在此之前 Agent 将先做纯只读的机制核实(评审 P0-5:t seat 真实机制——slots.register 的 locale 参数 vs ctx.slots.installLocale,对照官方 ui-settings-plugin-inventory 样板),确认后再动 catalog 与代码。

    首批落地对象:idle-archive / lan-proxy / mcp-manager / notifier / provider-usage / web-file-preview(6 个客户端包)。

  5. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    维护者授权确认(2026-08-31,口头授权视为批准)

    维护者在本会话明确选择「口头授权视为批准,直接开工」——Phase 3 i18n 落地正式启动(不再等 approved 标签;本评论 + 前述授权留痕(issue-comment-5474320874)即为批准依据)。

    落地将按计划执行:catalog 新增官方类型依赖(dsh-client-locale 等)→ 6 包 locales.ts + LocaleNamespaceMap 合并 + inject locale + 双通道翻译消费 → 每段全门禁 + 阶段 commit。第一批试点 1-2 个包,机制验证后再铺开。

  6. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    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 稳定复验。已加注释说明原因与移除条件。

    官方推荐用法核实

    • 官方 client 插件 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-locale README:ctx.locale.register(ns, {zh,en}) 注册、ctx.locale.bind(ns) / 框架 t seat 翻译、UI 挂载后注册字典免重载
    • 本插件运行时接线与官方完全一致;官方 monorepo 内靠 paths→源码 + project references 编译故无此问题,npm 消费者才踩发布物缺陷

    试点验收(dsh-idle-archive)

    • src/client/locales.ts:zh key 源 + en 全键对齐(Record<Key, string> 编译期锁平衡),覆盖弹窗/设置卡/toast 全文案
    • 双通道:ctx.locale.register/bind(原生 DOM)+ slots.register({ locale: NS })(React t seat)+ 语言切换 subscribe 重绑重绘
    • devDeps 仅 ui-slots(显式 import type + declare module)与 store(ui-slots 类型面传递依赖);dsh-client-locale 类型包未 import 不引入
    • tsconfig.json +rewriteRelativeImportExtensions(./locales.ts 后缀 emit 改写)
    • smoke 补 i18n 接入哨兵(NS / register / bind / 双语文案 / locale 参数)
    • 门禁 build/test/contract/pack:check 全绿,阶段 commit 8979268

    下一步

    按试点样板铺开其余 5 包(lan-proxy / mcp-manager / notifier / provider-usage / web-file-preview);notifier 边界维持既定:kind 走客户端字典、动态数据原样、toast.ps1 固定文案保留并文档明示。

  7. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    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 全键对齐(编译期锁平衡),覆盖设置卡/浮窗/面板/表单/错误态全部用户可见文案
    • 双通道接线(官方 ui-jobs 同款):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)
    • 模块级常量表延迟求值:EVENT/CHANNEL/STATUS 等表的 label 列改存字典 key,渲染期 t()(模块加载时 t 未装配,不能固化文案)
    • 共享模块零污染:providerBadgeText/fullscreenLabel 加可选 t 参数(缺省中文不变),宿主 bundle 不引入 client 字典
    • 文案驱动逻辑两处结构化重构:lan-proxy saved.indexOf("失败")、notifier saved.indexOf("失败")||"不可用" 改 msg+err 状态(英文态下字符串匹配必失效)
    • {PROVIDER} 字面占位样式经参数传值保持原文视觉(官方插值单遍替换、缺失参数保留原样,已核实实现)
    • 不翻译边界:console 日志、宿主端错误消息(「版本冲突」原文匹配为跨端契约)、引导指令(发给 Agent 的 prompt 数据)、toast.ps1 固定文案(按既定拍板保留)、未知 kind 等动态数据
    • 每包 smoke/契约测试补 i18n 接入哨兵(NS / register / bind / 双语字典样本 / locale 参数)

    验收

    • 6 包 build + test 全绿;仓库根全量门禁 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 type workaround(各文件均有注释标记)
    • Phase 1.5(lan-proxy 隔离实测)待维护者升级 dsh CLI 后按 dsh-verify-isolated 流程执行;i18n UI 的浏览器实测可在同轮隔离验证中一并截图归档
  8. unpinned this issue on Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-proposal-review需要维护者评审方案后再决定是否推进(在原 issue 讨论,不单开决策 issue)

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions