# pi-cn

把 Pi 界面变成「英文选项 + 中文注释」。功能名保留英文，说明文字变中文。

> 遇到漏译、误译或想加点什么，请到 [GitHub Issues](https://github.com/CYXyouzhi/pi-cn/issues) 反馈。
> 反馈漏译时带上「哪个插件 + 界面上看到的那行英文」，定位会快很多。

## 功能

- `/` 补全显示中文说明，新装的插件也会自动出现
- 常用命令排前面（按使用次数）
- `/model`、`/settings`、`/tree` 等界面文案变中文
- 设置界面覆盖完整：设置项名称（`Warnings`、`Theme`、`Apply` 这类单个词）与子页面选项一并汉化
- 插件自带官方中文语言包时直接采用作者的翻译（零 token，见下）
- `/汉化` 是管理入口，`/汉化 体检` 检查映射有没有误伤代码

## 两条轨道

界面文本有两条来源，优先走第一条：

**轨道一：插件官方语言包**（零 token）

插件若自带 `locales/en.json` + `locales/zh.json`，直接拿作者的翻译，不消耗模型额度。做法是把源码里的英文
换成 `英文（中文）`——这类插件的文案都经 `t(key, fallback)` 取出，语言包缺失时原样返回 fallback，
而 fallback 就是源码里的英文字面量，所以不需要任何第三方语言运行时。

三道筛子保证不误伤：源码里找不到的字面量、语言包缺中文的 key、位于导出对象内的值（可能同时参与逻辑校验）
一律跳过。最后一种对应真实事故：`ROW_INTENT_META.other.label` 既是显示文案，又是 `RESERVED_LABEL_SET`
的数据源，改了会让校验失效。

**轨道二：扫源码 + 模型翻译**

没有语言包的插件，按「位置 + 形态」两重判据提取：

- 位置：明确的显示容器与错误投递点（`new Text(` / `new Error(` / `.push(` /
  `ui.notify` 家族 / `setText` 家族 / `label:` / `title:` / 渲染 API 调用点）
- 形态：含空格的句子、或识别符形态的键名（`autoSelectSingleGoal`）
- 排除：日志、工具与参数 schema、命令注册作用域、导出对象成员、跨字符串残留

工具参数说明、遥测字段、枚举值与逻辑标识都会被排除。

## 安装

    pi install npm:pi-cn

装完重启 Pi。

## 命令

`/汉化` 不带参数会弹菜单，也可以直接指定：

    /汉化 自动     体检 + 翻译 + 应用
    /汉化 体检     检查映射风险
    /汉化 清除     还原英文
    /汉化 频率     清空使用统计

`/汉化 清除` 会把待汉化清单（含上面的黑名单）一并清掉，下次 `/汉化 自动` 重新完整扫描一遍。

## 覆盖范围

主程序（`/model`、`/thinking`、`/settings`、`/tree`、`/resume`、`/trust`、启动画面、更新提示），Pi 本体的设置界面与子页面（快捷键说明、设置项名称与当前值），`/plan`、`/goal`、`/btw` 三个插件，以及 pi-ui 通用组件。

覆盖的是 Pi 安装目录本体（`dist/bundle/chunks`、`dist/core`、`dist/tools`）加已装插件。工具参数说明、遥测字段、枚举值与逻辑标识等「给模型或逻辑用」的文本会被自动排除，不会误译。

## 注意

只改界面文字，发给模型的内容不动。补丁打在 Pi 安装目录里，改前按「安装版本」备份成 `<文件>.bak.<版本>`（如 `chunk-XXX.js.bak.1.0.0`），改后做语法校验，失败自动还原。备份名带版本的理由：Pi 升级后旧备份不会被当成新版本文件的备份，否则 `/汉化 清除` 会把旧版本代码写回新文件。卸载插件不会自动还原，用 `/汉化 清除`，或手动拿当前版本对应的 `.bak.<版本>` 覆盖。

`/汉化 体检` 挑三类风险：字符串既用于显示又参与逻辑比较，替换后判断可能失效；短词误伤更长的文案；Pi 升级后失效的旧映射。

替换是「整文件一次性」的：同一文件里任意一条替换改坏语法，整批都不能落盘。而扫描偶尔会把压缩代码误当成文案——实例：Cookie 解析里的 `if(value[0]==='"'){…}` 被正则跨引号抓出残片 `"')throw new Error("`，插上中文就变成 `throw new Error(（…）`。一条这样的残片会让主 chunk 里其余两百多条正常译文一起失效，而且因为整批没落盘，下次 `/汉化 自动` 会原样重演。现在的做法是：整批被语法校验拦下时二分定位坏条目（只校验、不写盘），剔掉它、其余照常落盘；被剔掉的候选记入黑名单，不再重复翻译也不重复重试。

翻译用当前选中的模型。当前模型若来自 opencode / opencode-go，请求会自动带上会话标识（该服务缺它会返回 400）。

## 数据文件

    ~/.pi/agent/commands-cn.json          命令中文说明
    ~/.pi/agent/commands-frequency.json   使用频率
    ~/.pi/agent/hanhua-auto.json          模型翻译生成的映射
    ~/.pi/agent/hanhua-dropped.json       被判定为「不是文案」而跳过的候选（黑名单）
    ~/.pi/agent/pi-cn-locale.json         插件官方语言包生成的映射
    ~/.pi/agent/pi-cn.json                Pi 装在非默认路径时指定 piDist

## License

MIT