pi-zh

pi coding agent / TUI 的最小侵入简体中文本地化。

不改 node_modules 里的 pi 源码，也不 fork pi-mono。通过 Node 的 module.registerHooks() 在加载 @earendil-works/pi-coding-agent 与 @earendil-works/pi-tui 的 dist/*.js 时，只替换字符串字面量 / 模板静态片段中的界面文案。

特性

• pi 本体零改动：pi update 后继续生效；新增/改动的英文文案自动回退英文
• 仅 TUI/CLI 界面：不改 system prompt，不改工具 description（模型行为与 token 成本不变）
• 词典以英文原文为 key，按模块文件作用域查找，再回退 _global
• CJK 布局安全：pi-tui 已用 visibleWidth / truncateToWidth，中文对齐/截断天然正确

使用

# 安装
npm i -g pi-zh

pi-zh --help
pi-zh            # 交互模式，参数与 pi 完全一致

# 或免安装
npx pi-zh

可选：

alias pi='pi-zh'                 # 日常用中文入口；随时可取消
PI_ZH_DISABLED=1 pi-zh ...       # 关闭汉化，等价原版 pi
PI_ZH_PI_ROOT=/path/to/pi-pkg    # 手动指定 pi 包根目录

结构

pi-zh/
├── bin/pi-zh.mjs          # 入口：装钩子 → import pi 的 cli.js
├── src/
│   ├── hook.mjs           # registerHooks load 钩子
│   ├── lexer.mjs          # 定位字符串/模板片段
│   ├── transform.mjs      # 按词典替换
│   ├── dict.mjs           # 词典加载与禁译清单
│   └── resolve-pi.mjs     # 定位已安装的 pi（见下方「定位 pi」）
├── dict/
│   ├── glossary.md        # 术语表
│   ├── _global.json
│   ├── coding-agent/      # 按模块分段的词典
│   └── tui/
└── tools/                 # extract / validate / coverage / assemble ...

定位 pi

resolve-pi.mjs 按顺序尝试：

1. PI_ZH_PI_ROOT 环境变量（显式指定，优先级最高）
2. import.meta.resolve 解析 @earendil-works/pi-coding-agent
3. 当前运行 node 的全局位置：它自己的 lib/node_modules、npm_config_prefix、npm root -g
4. 其它 node 版本树：nvm、fnm、volta、asdf、n、nodenv、nvs，以及 /usr/local、/usr

前三步描述的都是当前运行的 node。如果 pi 装在另一个 node 版本下（例如 nvm 默认版本切换过， 或 pi 装在 v26 而当前 PATH 指向 v22），前三步都看不到它，此时第 4 步兜底扫描并列的版本树。 各管理器的目录均尊重自身环境变量（NVM_DIR、FNM_DIR、VOLTA_HOME、ASDF_DATA_DIR、N_PREFIX）。

多个版本树都装了 pi 时，取 pi 版本号最高的那个，而非 node 版本最高的。

开发

npm test                   # 词法/替换/钩子/全量 dist 解析
npm run extract            # 从 pi dist 扫候选
npm run validate           # 词典机械校验
npm run coverage           # 候选 vs 词典覆盖率
npm run assemble           # work/out → dict/

范围说明

会译：斜杠命令描述、快捷键描述、设置/会话/模型选择器、--help、状态/错误提示、底栏 hint 等。

不译（设计如此）：

• system prompt 与工具 description / promptSnippet / promptGuidelines
• 斜杠命令名、CLI flag 名、环境变量名、工具名、模型/提供方 id
• 发给模型的压缩摘要提示词、shell/PowerShell 命令串、HTTP 头名
• RPC/json 子进程通道（非交互）

升级 pi 后若出现新的英文界面文案：npm run extract && npm run coverage -- --missing 可列出缺口，补词典后再 npm run assemble。

License

Unlicense — public domain.