cc-zh

1import type { Register } from 'claude-code'
2
3// ── cc-zh：Claude Code 简体中文 UI mod ─────────────────────────────────────────
4// 设计要点（与社区先例 ko-ui 的差异）：
5//   1. **以「引擎给的英文原文」为查表键**，而不是按命令名/配置键枚举。
6//      `command.describe` 的 `next(e)` 本就返回引擎的英文描述 ⇒ 直接查 exact 表。
7//      好处：① 存量扁平表（1894 条 en→zh）可原样复用；② 版本升级后英文一变，
8//      只是「命不中、放行原文」，不会译错。
9//   2. 全部走 **props 透传改写**（`next({ ...e, props })`），由引擎用自己的组件绘制
10//      ⇒ 布局/配色/键位/交互不变；props 不合法时引擎退回原文绘制，不会崩。
11//   3. 命不中的字符串写进 `$.store`，由 `/cc-zh-dump` 列出 ⇒ 词典可增量攒。
12//   4. 零 token、零网络：只有一次 `$.fs.read` 读静态词典。
13
14type Pattern = { re: string; to: string }
15
16type Dict = {
17  exact: Record<string, string>
18  spinner: Record<string, string>
19  modes: Record<string, string>
20  patterns: Pattern[]
21}
22
23const EMPTY: Dict = { exact: {}, spinner: {}, modes: {}, patterns: [] }
24
25const MISSING_MAX = 400
26const ANSI = new RegExp('\\u001b\\[[0-9;]*m', 'g')
27const CJK = /[\u4e00-\u9fff]/
28// 键位类词不算「未译完」：ctrl / shift / alt / esc / tab / enter / cmd / opt / fn
29const KEYS = /\b(ctrl|shift|alt|esc|tab|enter|cmd|opt|fn)\b[+\w-]*/gi
30// ⚠️ 实测坑（2026-10-12，本仓测试发现）：守卫若只放行键位词，会把 CLI / API / MCP
31// 这类**全大写缩写**与 Git / GitHub 这类**专有名词**误判为「未译完」，导致含它们
32// 的提示行永远不替换。故须一并豁免。
33const ACRONYM = /\b[A-Z][A-Z0-9]{1,}\b/g
34const PROPER = /\b(Claude|Git|GitHub|Bash|Read|Write|Edit|Grep|Glob|Opus|Sonnet|Haiku|Fable|Mythos|Astra|Vim|Emacs)\b/g
35
36let dict: Promise<Dict> | undefined
37let queue: Promise<unknown> = Promise.resolve()
38const seen = new Set<string>()
39
40function load($: any): Promise<Dict> {
41  dict ??= $.fs
42    .read(`${$.plugin.root}/dict.json`)
43    .then((t: string) => ({ ...EMPTY, ...JSON.parse(t) }))
44    .catch(() => EMPTY)
45  return dict
46}
47
48/** 记录「仍是英文」的文案，供 /cc-zh-dump 列出。不翻译、不猜测。 */
49function record($: any, kind: string, text: string) {
50  const t = (text ?? '').replace(ANSI, '').trim()
51  if (!t || CJK.test(t) || t.length > 2000) return
52  const line = `[${kind}] ${t}`
53  if (seen.has(line)) return
54  seen.add(line)
55  queue = queue.then(async () => {
56    const old = ((await $.store.get('missing')) as string[] | undefined) ?? []
57    if (old.includes(line) || old.length >= MISSING_MAX) return
58    await $.store.set('missing', [...old, line])
59  })
60}
61
62/** exact 命中 → patterns 兜底；都不中则原样返回。 */
63export function tr(d: Dict, text: string): string {
64  const bare = text.replace(ANSI, '')
65  const hit = d.exact[bare]
66  if (hit) return hit
67  let out = bare
68  for (const p of d.patterns) {
69    try {
70      out = out.replace(new RegExp(p.re, 'gm'), p.to)
71    } catch {
72      // 词典里的正则写错，跳过该条
73    }
74  }
75  return out
76}
77
78/**
79 * 与 `tr` 同源，但**区分「译到了」与「原样放行」**：没译到一律返回 undefined。
80 *
81 * 为什么需要它：`command.describe` 的 key 是引擎给的整句描述，调用方必须能分辨
82 * 「命中」与「未命中」。而该处原先只做裸 exact 查表、不过 patterns ⇒
83 * 带**运行时变量**的描述（`/model` 的 `(currently …)`、`/fast` 的 `(Opus)`、
84 * `/sandbox` 的状态）结构性无法汉化。此函数让 patterns 在这条路径上生效。
85 */
86export function trDesc(d: Dict, text: string): string | undefined {
87  const bare = text.replace(ANSI, '')
88  const out = tr(d, text)
89  return out === bare ? undefined : out
90}
91
92/**
93 * Spinner 用词：**只在当前词仍是英文时**才接替；已含中文一律放行。
94 *
95 * 为什么必须这样：用户很可能已经用官方 `settings.json` 的 `spinnerVerbs`
96 * 配了自定义中文动词（例如「烘焙中」「焯水ing」），此时 `props.word` **本来就是中文**。
97 * 若无条件用固定词表覆盖，等于把别人的趣味动词换成「思考中」，是体验退化。
98 *
99 * @returns `word` 最终采用的词（原样返回时保持 `undefined` 语义）；`missed` 表示
100 *          「当前仍是英文，但词典里没有对应词」—— 供 `/cc-zh-dump` 收集。
101 */
102export function spinnerWord(
103  d: Dict,
104  mode: string,
105  current?: string,
106): { word?: string; missed: boolean } {
107  if (CJK.test(String(current ?? ''))) return { word: current, missed: false }
108  const zh = d.spinner[mode]
109  if (!zh) return { word: current, missed: true }
110  return { word: zh, missed: false }
111}
112
113/**
114 * 提示行文案：只有「整句都译到」才接受，否则放行原文。
115 * 理由：提示行是短句，半英半中的观感比全英文更差（ko-ui 同判据）。
116 */
117export function trWhole(d: Dict, text: string): string | undefined {
118  const out = tr(d, text)
119  if (out === text.replace(ANSI, '')) return undefined
120  const rest = out.replace(KEYS, '').replace(ACRONYM, '').replace(PROPER, '')
121  return /[A-Za-z]{3,}/.test(rest) ? undefined : out
122}
123
124const GROUP_ORDER = ['search', 'read', 'list', 'shell']
125const GROUP_OF: Record<string, string> = {
126  Grep: 'search', Glob: 'search', Read: 'read', LS: 'list', Bash: 'shell', PowerShell: 'shell',
127}
128const GROUP_TEXT: Record<string, (n: number, active: boolean) => string> = {
129  search: (n, a) => `检索 ${n} 次${a ? '进行中' : '已完成'}`,
130  read: (n, a) => `读取 ${n} 个文件${a ? '中' : ''}`,
131  list: (n, a) => `列出 ${n} 个目录${a ? '中' : ''}`,
132  shell: (n, a) => `执行 ${n} 条命令${a ? '中' : ''}`,
133}
134
135export function groupLine(calls: ReadonlyArray<{ tool: string }>, active: boolean): string | undefined {
136  const count: Record<string, number> = {}
137  for (const c of calls) {
138    const g = GROUP_OF[c.tool]
139    if (!g) return undefined // 含未知工具 ⇒ 交给引擎原文
140    count[g] = (count[g] ?? 0) + 1
141  }
142  const parts = GROUP_ORDER.filter(g => count[g]).map(g => GROUP_TEXT[g](count[g], active))
143  return parts.length > 0 ? parts.join('，') : undefined
144}
145
146export function duration(ms: number): string {
147  const s = Math.max(0, Math.round(ms / 1000))
148  const h = Math.floor(s / 3600)
149  const m = Math.floor((s % 3600) / 60)
150  const r = s % 60
151  if (h > 0) return `${h} 小时 ${m} 分`
152  if (m > 0) return `${m} 分 ${r} 秒`
153  return `${r} 秒`
154}
155
156/** 列出「仍是英文且不在词典里」的命令、配置项与屏幕文案。 */
157async function scan($: any) {
158  const d = await load($)
159  const need = (t?: string) => !!t && t.trim() !== '' && !CJK.test(t) && !d.exact[t.trim()]
160  const todo: { commands: Record<string, string>; config: Record<string, string>; texts: string[] } =
161    { commands: {}, config: {}, texts: [] }
162
163  const commands: any[] = await $.command.list()
164  for (const c of commands) {
165    if (c.plugin !== 'cc-zh' && need(c.description)) todo.commands[c.name] = c.description
166  }
167  const config: any[] = await $.config.list()
168  for (const r of config) {
169    if (need(r.label)) todo.config[r.key] = r.label
170  }
171  todo.texts = ((await $.store.get('missing')) as string[] | undefined) ?? []
172  return todo
173}
174
175export const register: Register = on => {
176  on('session.start', async ($, e, next) => {
177    await $.command.register({
178      name: 'cc-zh-dump',
179      description: '列出词典里还没有中文的命令、配置项与屏幕文案',
180    })
181    // 词典是异步读的，读完让这两处重算一次
182    await $.ui.invalidate('command.describe')
183    await $.ui.invalidate('config.describe')
184    $.clock.after(8000, async () => {
185      const t = await scan($)
186      const n = Object.keys(t.commands).length + Object.keys(t.config).length
187      if (n > 0) {
188        await $.ui.toast(`cc-zh：发现 ${n} 处未译项，输入 /cc-zh-dump 查看`)
189      }
190    })
191    return next(e)
192  })
193
194  on('command.run', { command: 'cc-zh-dump' }, async $ => {
195    const t = await scan($)
196    const cmds = Object.entries(t.commands).map(([k, v]) => `- /${k}: ${v}`)
197    const cfgs = Object.entries(t.config).map(([k, v]) => `- ${k}: ${v}`)
198    const lines = [
199      `未译项：命令 ${cmds.length}，配置 ${cfgs.length}，屏幕文案 ${t.texts.length}`,
200      ...(cmds.length ? ['', '[命令说明]', ...cmds] : []),
201      ...(cfgs.length ? ['', '[配置项]', ...cfgs] : []),
202      ...(t.texts.length ? ['', '[屏幕文案]', ...t.texts.slice(0, 80).map(x => `- ${x}`)] : []),
203      '',
204      '把上面的英文原样作为 key 加进 dict.json 的 exact 即可（值填中文）。',
205    ]
206    return { text: lines.join('\n') }
207  })
208
209  // ── 斜杠命令说明（`/` 弹出的那一栏）──
210  on('command.describe', async ($, e, next) => {
211    const d = await load($)
212    const r = await next(e)
213    const zh = trDesc(d, r.description ?? '')
214    if (zh === undefined) {
215      record($, `cmd:${e.command}`, r.description ?? '')
216      return r
217    }
218    const hint = r.argumentHint ? trDesc(d, String(r.argumentHint)) : undefined
219    return { ...r, description: zh, argumentHint: hint ?? r.argumentHint }
220  })
221
222  // ── /config 行 ──
223  on('config.describe', async ($, e, next) => {
224    const d = await load($)
225    const r = await next(e)
226    const label = d.exact[(r.label ?? '').trim()]
227    const desc = d.exact[(r.description ?? '').trim()]
228    if (!label) record($, `config:${e.key}`, r.label ?? '')
229    return { ...r, label: label ?? r.label, description: desc ?? r.description }
230  })
231
232  // ── 工作态 Spinner ──
233  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
234    if (e.surface !== 'terminal') return next(e)
235    const d = await load($)
236    const p = e.props
237    let message = p.message
238    if (message !== null && message !== undefined) {
239      const out = tr(d, message)
240      if (out === String(message).replace(ANSI, '')) record($, 'spinner', message)
241      else message = out
242    }
243    const { word, missed } = spinnerWord(d, p.mode, p.word)
244    if (missed) record($, `spinner-mode`, p.mode)
245    return next({ ...e, props: { ...p, word, message } })
246  })
247
248  // ── 提示行（整句译到才替换）──
249  on('ui.render', { component: 'PromptHint' }, async ($, e, next) => {
250    const d = await load($)
251    const out = trWhole(d, e.props.hint ?? '')
252    if (out === undefined) {
253      record($, 'hint', e.props.hint ?? '')
254      return next(e)
255    }
256    return next({ ...e, props: { ...e.props, hint: out } })
257  })
258
259  // ── 通知条 ──
260  on('ui.render', { component: 'InfoNotice' }, async ($, e, next) => {
261    const d = await load($)
262    const text = e.props.text ?? ''
263    const out = tr(d, text)
264    if (out === text.replace(ANSI, '')) {
265      record($, 'notice', text)
266      return next(e)
267    }
268    return next({ ...e, props: { ...e.props, text: out } })
269  })
270
271  // ── 页脚模式标签 ──
272  on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
273    const d = await load($)
274    const modes = e.props.modes.map((m: string) => {
275      const zh = d.modes[m]
276      if (!zh) record($, 'mode', m)
277      return zh ?? m
278    })
279    return next({ ...e, props: { ...e.props, modes } })
280  })
281
282  // ── `(ctrl+b to run in background)` ──
283  on('ui.render', { component: 'ToolProgress' }, async ($, e, next) => {
284    const hint = e.props.hint ?? ''
285    const m = /^\((.+) to run in background\)$/.exec(hint)
286    if (!m) {
287      record($, 'progress', hint)
288      return next(e)
289    }
290    return next({ ...e, props: { ...e.props, hint: `（${m[1]} 转后台运行）` } })
291  })
292
293  // ── 命令输出行 ──
294  on('ui.render', { component: 'CommandOutput' }, async ($, e, next) => {
295    const d = await load($)
296    const text = e.props.text ?? ''
297    const out = tr(d, text)
298    if (out === text.replace(ANSI, '')) {
299      record($, `out:${e.props.command}`, text)
300      return next(e)
301    }
302    return next({ ...e, props: { ...e.props, text: out } })
303  })
304
305  // ── 后台任务通知（引擎自绘，透传改写）──
306  on(
307    'ui.render',
308    { component: 'UserMessage', props: { origin: { kind: 'task-notification' } } },
309    async ($, e, next) => {
310      const d = await load($)
311      const text = e.props.text ?? ''
312      const out = tr(d, text)
313      if (out === text.replace(ANSI, '')) {
314        record($, 'task-notification', text)
315        return next(e)
316      }
317      return next({ ...e, props: { ...e.props, text: out } })
318    },
319  )
320
321  // ── 折叠的工具调用摘要（自绘，因为译文长度与原文不同）──
322  on('ui.render', { component: 'ToolGroup' }, async ($, e, next) => {
323    if (e.props.isExpanded) return next(e)
324    const line = groupLine(e.props.calls, e.props.isActive)
325    if (line === undefined) {
326      record($, 'toolgroup', e.props.calls.map((c: any) => c.tool).join(','))
327      return next(e)
328    }
329    const { Box, Text } = $.ui.resolve(e)
330    return (
331      <Box flexDirection="row">
332        <Text dimColor>
333          ● {line}
334          {e.props.isActive ? '…' : ''}
335        </Text>
336        <Text dimColor>（ctrl+o 展开）</Text>
337      </Box>
338    )
339  })
340
341  // ── 轮次结束行（自绘，中文时长）──
342  on('ui.render', { component: 'TurnDuration' }, async ($, e) => {
343    const { Text } = $.ui.resolve(e)
344    return <Text dimColor>✻ 耗时 {duration(e.props.durationMs)}</Text>
345  })
346}
347