66 lines
4.2 KiB
Markdown
66 lines
4.2 KiB
Markdown
# 跟随 DSH 的 i18n(ctx.locale)设计
|
||
|
||
> 2026-08-12 · 随 v0.8.2 发布
|
||
|
||
## 背景
|
||
|
||
better-sidebar 的界面文案(约 260 处 `t()` 调用、28 个文件)此前自带 zh/en 词典并直接读
|
||
`navigator.language`(`src/client/locales.ts` 头注释曾明言"renders outside the slot
|
||
system's locale seat, so it reads the browser language directly")。问题:
|
||
|
||
- DSH 的语言偏好是 Host-backed(`locale.preference`,存于 `$DSH_HOME/settings.yaml`),
|
||
用户设置与浏览器语言不一致时侧边栏不跟随(如偏好 zh、浏览器 en 时侧边栏仍为英文)。
|
||
- 词典游离在 DSH 的 i18n 注册表之外,无法参与公共命名空间回退等机制。
|
||
|
||
DSH 的 i18n 系统(`@deepseek-ai/dsh-client-locale`):
|
||
|
||
- `ctx.locale` 服务(client-only):`getSnapshot()/subscribe()` 是 LocaleFace
|
||
(uSES 安全,revision 递增),`locale/change` 事件在切换时触发;
|
||
- `ctx.locale.register(ns, {zh, en})` 命名空间词典注册(typed 变体要求合并
|
||
`LocaleNamespaceMap`);查询链 ns → common → zh → key;
|
||
- 所有 DSH 客户端包以 `inject = [..., 'locale']` 消费。
|
||
|
||
## 设计决策
|
||
|
||
1. **结构镜像服务**(仓库惯例,`src/context-types.ts` 头注释):本插件解析在 DSH
|
||
monorepo 单一 cordis 实例之外,上游 `declare module 'cordis'` augmentation 不达此
|
||
Context。新增 `SidebarLocaleService` 结构脸(只镜像用到的切片:
|
||
`getSnapshot` / `subscribe` / `register`),merge `Context.locale`。不引入
|
||
`@deepseek-ai/dsh-client-locale` 依赖、不做 value import(client bundle 纯度门)。
|
||
2. **保留模块级 `t()`**:`t()` 被 28 个文件使用,穿 props 不可行。改为模块级 holder:
|
||
`apply()` 调 `attachLocale(ctx.locale)`,`t()`/`isZh()` 从 holder 读活跃 locale;
|
||
无 holder 时回退既有 `navigator.language` 检测(行为与改动前完全一致,也是 jsdom
|
||
测试与非标准组合的降级路径)。
|
||
3. **根级重渲染触发**:侧边栏自行 `createRoot` 挂在 slot 系统之外,拿不到 `t` seat。
|
||
在 `Sidebar.tsx` 根组件加 `useSyncExternalStore(ctx.locale.getSnapshot/subscribe)`
|
||
(该文件已用此 API 订阅 sessions/store);树内无 `React.memo`,根重渲染即整树
|
||
重渲染,所有渲染期 `t()` 求值读到新语言。事件期调用(intercept、api、subagent-tasks)
|
||
在调用时刻读当前语言,天然正确。SideCardSection 由 settings shell 渲染,shell 自身
|
||
订阅 locale revision(ui-settings-general 的 section rows 缓存含 locale revision),
|
||
自动跟随。
|
||
4. **命名空间 `'betterSidebar'`**:`'sidebar'` 已被 DSH 的 ui-sidebar 占用。注册走
|
||
非类型化单语言重载 `register(ns, locale, dict)`(DSH 内 ui-permission 同款先例);
|
||
键型安全由本地 `const en: Record<keyof typeof zh, string>` + 测试键集相等断言保证。
|
||
5. **词典注册进 DSH 注册表**:`ctx.effect` 内注册 zh/en 并返回合并 disposer
|
||
(fiber 卸载时撤销,HMR 重激活不抛 "already registered")。
|
||
6. **xlsx 预览的 Univer locale pack**:`xlsx-view.tsx` 原内联 navigator 检测改走
|
||
`isZh()`(跟随 DSH 语言;Univer 实例在挂载时创建,语言切换不重建实例——可接受)。
|
||
|
||
## 实施偏差记录
|
||
|
||
- 无。计划与实施一致。
|
||
- 版本号随 v0.8.2 发版提交(`package.json` + `dsh.plugin.json`)。
|
||
- v0.8.2 后补遗:md 预览(`TextEditor.tsx`)的代码块复制按钮文案——DSH 的
|
||
`MarkdownText`/`CodeBlock` 是 cordis-free 组件,未传 `codeLabels` 时回退到硬编码中文
|
||
「复制/复制成功」。修复为渲染时传入 `codeLabels={{ copyLabel: t('copy'), copiedLabel: t('copied') }}`
|
||
(对齐 DSH 聊天区 `AssistantMarkdown` 的做法),新增 `tests/markdown-copy-labels.spec.tsx`
|
||
钉住 zh/en 跟随。
|
||
|
||
## 验收
|
||
|
||
- `pnpm typecheck` / `pnpm test` / `pnpm build`(纯度门)全绿;`tests/locales.spec.ts`
|
||
覆盖:无服务回退、attach 后跟随活跃 locale 实时切换、detach 恢复回退、占位符插值、
|
||
relativeTime 链路、命名空间名、zh/en 键集相等。
|
||
- 手动:设置页切换语言 → 侧边栏全部文案实时切换;`locale.preference: zh` 且浏览器 en
|
||
→ 侧边栏中文。
|