Skip to content

fix(cosh-ng): [shell] localize the zh-CN /help group titles and agent hint - #3342

Open
Forrest-ly wants to merge 1 commit into
agentic-os-org:mainfrom
Forrest-ly:fix/gh-3336-zh-help-panel-i18n
Open

Forrest-ly wants to merge 1 commit into
agentic-os-org:mainfrom
Forrest-ly:fix/gh-3336-zh-help-panel-i18n

Conversation

@Forrest-ly

Copy link
Copy Markdown
Collaborator

背景

#3336:zh-CN 下 /help 面板的 8 个分组标题里还有英文,/agent 的摘要用了「组稿」这个编辑/新闻用语,读起来不通顺。修复前实际渲染:

│ Registry                     ← 未翻译
│   /agent            [session]
│       组稿一次性 Agent 请求    ← 用词不当
│ Hooks                        ← issue 允许保留,见下
│   /hooks          [read-only]
│       显示 Hook 状态

改动

文件 改动
src/cosh-ng/crates/cosh-shell/src/i18n/zh/help.rs HelpGroupRegistry:Registry → 注册表;HelpSummaryAgent:组稿一次性 Agent 请求 → 编写一次性 Agent 请求;HelpGroupHooks 保留 Hooks 并就地写明理由(+8 −2)
src/cosh-ng/crates/cosh-shell/tests/raw_cli/i18n.rs 新增 HELP_ZH_FORBIDDEN_UI(8 条),补齐 help 面板缺失的英文残留守护(+14)
src/cosh-ng/crates/cosh-shell/tests/raw_cli/slash.rs 新增 raw_cli_help_renders_zh_group_titles:在 COSH_SHELL_LANG=zh-CN 下渲染 /help,钉住 8 个分组标题与 /agent 摘要,并断言英文标题不出现(+34)

不改 en 目录,不改 slash/notices.rs 里的内部分组 key(("Registry", MessageId::HelpGroupRegistry) 是与 hint.group 比对的标识符,不是 UI 文案),不改 workflow。

为什么 Registry 译成「注册表」

zh 用户指南里所有 registry 概念本来就叫「注册表」:「远程技能注册表」(copilot-shell/skills.md)、「Clawhub 注册表 URL」(copilot-shell/configuration.md)、OpenClaw 的「插件工具注册表」(token-saving/agent-memory.md)。zh 文档和 zh 文案里没有任何一处使用英文 Registry,所以这是沿用既有术语,不是新造词。

为什么 Hooks 保留英文(issue 允许的第二种做法)

#3336 原话是「HelpGroupHooks → "钩子"(or keep "Hooks" if product convention prefers the English loanword, but it should be consistent with HelpSummaryHooks which uses "Hook 状态")」。两个条件都成立:

  • zh 文案里 Hook / Hooks 共出现 161 次、分布在 9 个 zh message 文件;「钩子」在整个 cosh-ng 里出现 0 次;
  • 同组内紧邻的条目 HelpSummaryHooks 就是「显示 Hook 状态」;zh/health.rs 的采集项标签是 HealthCollectorHooks => "Hooks",zh/hooks.rs 是「已注册 {count} 个 Hook。」,zh/approval.rs 是「Hook 审查」。

只把标题译成「钩子」,会让「钩子」正好压在「显示 Hook 状态」的上一行。Prompt 属于同类借词(「Prompt 草稿卡」),同理不动。这两个决定现在都写进了断言,不再靠运气。

为什么顺手补守护测试

help 是唯一没有 *_ZH_FORBIDDEN_UI 清单的 zh 面板:approval / details / provider_native / renderer / question / slash_config / mode 七个都有。这正是英文标题能一路发布出去的原因,按同样约定补齐后,新增分组不可能再悄悄带着英文标题落地。

测试情况

环境:Linux x86_64;base = main 713dc2f8;rustc 1.96.0;Node v22.21.1。

命令 结果
cargo test -p cosh-shell --test raw_cli -- slash:: config:: mode:: i18n 47 passed / 0 failed(含新 zh 用例与既有 en-US help 用例)
cargo test -p cosh-shell --lib -- i18n:: 8 passed
cargo fmt --all -- --check 干净
cargo clippy -p cosh-shell --all-targets -- -D warnings 干净(62.8s)
渲染结果人工核对 8 个标题正确;「注册表」比「Registry」窄 3 个单元格,面板边框仍然对齐;footer 未受影响

负向对照(证明守护真的拦得住)

变异 结果
注册表 → Registry 新用例失败:missing zh group header 注册表
编写 → 组稿 新用例失败:assert!(!normalized.contains("组稿一次性"))
会话 → 会话 Sessions 新用例失败:migrated English UI label leaked: Sessions(单独验证 HELP_ZH_FORBIDDEN_UI 生效)

每次变异后都还原文件,最终 git status 只剩上表 3 个改动文件。

全量套件与基线对照

cargo test -p cosh-shell --no-fail-fast:5060 passed / 15 failed。15 个失败在未改动的 pristine main 713dc2f8 上完全同样地失败,与本次改动无关:

失败集合 本分支 基线 main
raw_cli zsh/PTY 11 个(daily_terminal 4、terminal_unicode 4、terminal_ownership 1、native 1、startup 1) 7 passed / 11 failed 7 passed / 11 failed(同样 11 个用例)
lib fd_reader_waits_for_readiness_without_backoff 1493 / 1 failed 1493 / 1 failed
bin activity_tool_output_details_show_internal_output_ref_in_debug 2732 / 1 failed 2732 / 1 failed
shell_host relay::raw_relay_bash_shell_opaque_bytes_ignore_slash_route、termios::scripted_shell_exit_timeout_kills_foreground_group 单独跑 2 passed 单独跑 2 passed(并行负载下的 flake)

未运行:其他 crate 与 cosh-core / cosh-gateway 套件——本次改动只落在 cosh-shell 的 zh help 文案与其 raw_cli 测试内。

与在途 PR 的冲突核对

#3312 是另一个改 cosh-shell i18n 的在途 PR:它改 i18n/mod.rs(hunk 在 @@111 / @@126,tests 模块开头)、i18n/{en,zh,message_id}/health.rs,以及 tests/raw_cli/slash.rs(hunk 在 @@73,即 en-US help 用例内部)。本 PR 改 i18n/zh/help.rs、tests/raw_cli/i18n.rs(#3312 未触及)和在 slash.rs 文件末尾追加的新用例,与 #3312 的 hunk 无文本重叠。

Fixes #3336

@github-actions github-actions Bot added the component:cosh-ng src/cosh-ng label Sep 18, 2026
@SunnyQjm

Copy link
Copy Markdown
Collaborator

PR number: #3342
head_sha: 0fcb727
reviewed_at: 2026-09-18T08:15:32Z

未发现 blocking package/module/public API 组织问题。

剩余风险:未独立运行测试;当前 CI 快照中 fast checks 和 commit lint 失败,Test cosh-ng 仍在运行,合并前需确认结果。

… hint

The zh-CN /help panel left one of its eight group headers in English and
described /agent with 组稿, which is editorial copy ("compile a manuscript")
rather than "compose a request":

    │ Registry                  ->  │ 注册表
    │   /agent                        │   /agent
    │       组稿一次性 Agent 请求      ->  │       编写一次性 Agent 请求

Registry becomes 注册表, the term the zh user guide already uses for every
other registry in the product ("远程技能注册表", "Clawhub 注册表 URL",
OpenClaw 的插件工具注册表); no zh doc or zh message uses the English word.

Hooks deliberately stays English. Issue 3336 allows either spelling and asks
for consistency with HelpSummaryHooks, and the zh catalog is unanimous:
Hook/Hooks appears 161 times across nine zh message files while 钩子 appears
nowhere in cosh-ng -- not in the entry rendered inside this very group
("显示 Hook 状态"), not in zh/health.rs' HealthCollectorHooks label ("Hooks"),
not in zh/hooks.rs' "已注册 {count} 个 Hook。" and not in zh/approval.rs'
"Hook 审查". Translating only the header would put 钩子 one line above
"显示 Hook 状态". Prompt is the same kind of loanword ("Prompt 草稿卡") and
stays for the same reason. Both decisions are now asserted in code instead of
being left to chance.

The panel was the only zh panel with no forbidden-label guard, which is how
this shipped: the other seven carry a *_ZH_FORBIDDEN_UI list in
tests/raw_cli/i18n.rs. Add HELP_ZH_FORBIDDEN_UI plus
raw_cli_help_renders_zh_group_titles, which renders /help under
COSH_SHELL_LANG=zh-CN and pins all eight headers, the /agent summary, and the
absence of the English titles. The en-US panel is untouched.

Tests (Linux x86_64, base main 713dc2f, rustc 1.96.0):

- cargo test -p cosh-shell --test raw_cli -- slash:: config:: mode:: i18n
  gives 47 passed, 0 failed (new zh test + the existing en-US help test)
- cargo test -p cosh-shell --lib -- i18n:: gives 8 passed
- cargo fmt --all -- --check is clean
- cargo clippy -p cosh-shell --all-targets -- -D warnings is clean, 62.8s
- negative control 注册表 -> "Registry": the new test fails with
  "missing zh group header 注册表"
- negative control 编写 -> 组稿: the new test fails at the 组稿一次性 assertion
- negative control 会话 -> "会话 Sessions": the new test fails with
  "migrated English UI label leaked: Sessions", which exercises
  HELP_ZH_FORBIDDEN_UI on its own
- rendered zh panel inspected: all eight headers correct, borders still
  aligned (注册表 is 3 cells narrower than Registry), footer untouched
- cargo test -p cosh-shell --no-fail-fast (full) gives 5060 passed and
  15 failed; every failure also fails on pristine main 713dc2f: the same
  11 raw_cli zsh/PTY tests (7 passed / 11 failed on both), the same 2
  lib+bin timing tests (1493/1 and 2732/1 on both), and 2 shell_host tests
  that pass in isolation on both branch and baseline (parallel-load flakes)
- not run: other crates and the cosh-core/cosh-gateway suites, since no code
  outside cosh-shell's zh help catalog and its raw_cli tests changed

Fixes agentic-os-org#3336

Co-authored-by: multica-agent <github@multica.ai>
@Forrest-ly

Copy link
Copy Markdown
Collaborator Author

已修 CI 两项失败 — head 0fcb7279 → 3876c068(tree 逐字节未变)

force-push 只改 commit message,git rev-parse 0fcb7279^{tree} 与 3876c068^{tree} 同为 4be8115a,代码零改动,已给出的 review 上下文不受影响。

1. 📝 Commit Message Lint(硬门禁,之前 FAILURE)

报错只有一条:footer's lines must not be longer than 100 characters [footer-max-line-length]。

根因不是「表格太长」,而是 body / footer 的切分点:conventional-commits-parser 是逐行扫描的,第一处出现 issue 引用(#3336)的行会把 isBody 置为 false,此后所有行都算 footer。原 message 里正文第 16 行就写了 Hooks deliberately stays English. #3336 allows either spelling...,于是后面整张测试表格都被判成 footer。而 .github/commitlint.config.json 里 body-max-line-length 是 level 1(warning,不失败)、footer-max-line-length 继承 config-conventional 的 level 2(error,失败)——同一批长行放在 body 里只是 warning,落到 footer 就成了硬失败。

这也解释了为什么 main 上带同样长表格的 commit(67dd3a1b 8 行超 100、8c8a1c8f 3 行超 100)能过:它们全文没有任何 #数字 引用,所有行都留在 body。

修法(不改任何事实内容):

  • 正文里的 #3336 改成 Issue 3336,链接由结尾的 Fixes #3336 提供;
  • 测试结果表改写成折行列表,全文 每一行 ≤ 100 字符,这样无论解析器把切分点放在哪里都不会触发 error;
  • Fixes #3336 与 Co-authored-by 收在最后。

本地用 commitlint 19 + 仓库自带的 .github/commitlint.config.json 验证:原 message exit=1(复现同一条 error),新 message exit=0。

2. Test cosh-ng fast checks(之前 FAILURE,与本 PR 无关)

挂的是 ecs_probe::configure_response_does_not_wait_indefinitely_for_process_exit,属 tests/protocol 二进制;本 PR 只动 src/i18n/zh/help.rs 与两个 tests/raw_cli/* 文件,两者无交集,是既有 flake:该用例在 registry_query 发起之前就开始轮询 fixture 的 pid 文件,5 秒预算要覆盖主线程被调度、fork /bin/sh、shell 读请求、mkfifo、printf 写 pid,而 fast 门禁用 --test-threads=4 在共享 runner 上并跑其他会 spawn 进程的用例。

已单独开 #3349 修(纯测试改动,把这一个被混用的 5 秒预算拆成「宿主调度预算」和「产品断言预算」两个具名常量,并附可复现的负向对照)。本轮不把它塞进本 PR,避免污染 zh-CN 本地化的 review 范围。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(cosh-ng): /help panel has untranslated group titles and awkward agent hint in zh-CN

2 participants