pen.dev 中文汉化 (pen-zh)
将 pen.dev 编辑器界面一键汉化为简体中文的 VS Code 扩展。当前词典对标 pen.dev 插件(highagency.pencildev)0.6.77 版本。
特性
- 启用即生效,禁用即还原:扩展激活时自动将中文写入 pen.dev 的编辑器资源;停用/卸载时自动还原为英文,不影响 pen.dev 原插件功能。
- 兼容 pen.dev 自动更新:pen.dev 会在后台下载并覆盖其编辑器资源(webview bundle),旧版汉化插件因此会“失效”。本插件通过文件系统监听,在 pen.dev 覆盖资源后自动重新注入中文,稳定可用。
- 双层汉化策略:
- 词条替换(fileReplacements):对
editor/assets/*.js 中的多词英文界面文案做子串替换(工具提示、面板说明、菜单项等)。仅替换完整短语,不会误伤代码标识符。
- 运行时 DOM 翻译(domReplacements):向
editor/index.html 注入一段轻量脚本,在运行时翻译单字标签(工具名、面板名等),并通过 MutationObserver 覆盖动态渲染的文本节点与 title/aria-label/placeholder 属性。
- 幂等且可还原:替换只在“原文存在、译文不存在”时发生,因此重复应用安全无副作用;还原通过反向替换(
to → from)实现,即使 pen.dev 已更新到新版本也能正确还原。
原理
pen.dev 的编辑器 webview 实际从 扩展安装目录 加载(0.6.6x+ 架构,见其
out/main-*.js 中 Uri.joinPath(extensionUri, "out", "editor")):
<extensions目录>/highagency.pencildev-<版本>/out/editor/assets/*.js
<extensions目录>/highagency.pencildev-<版本>/out/editor/index.html
本插件直接修改这些运行时副本(修改前自动备份到本插件自己的 globalStorage
pen-zh-backups/,可完整还原),不改动 pen.dev 的逻辑代码,因此不会破坏原插件功能。
使用
- 将本扩展文件夹放入 VS Code 的扩展目录(例如
extensions/pen-zh/),重启 VS Code。
- 扩展随 VS Code 启动自动启用并应用中文。重新打开 pen.dev 编辑器标签页即可看到效果。
- 若需手动控制,可在命令面板(
Ctrl/Cmd+Shift+P)运行:
pen.dev 汉化:应用中文
pen.dev 汉化:恢复英文
pen.dev 汉化:重新应用(刷新) —— 当 pen.dev 更新后部分词条未命中时使用。
维护词条
翻译词条集中在 patches/translations.json:
fileReplacements:多词英文短语 → 中文(安全的文件级替换)。
domReplacements:单字/单词标签 → 中文(运行时 DOM 翻译)。
pen.dev 升级后的词典同步流程
pen.dev 每次升级都可能改动 bundle 文案或压缩变量名,按以下流程同步:
- 扫描:
npm run scan(自动发现本机最新版 pen.dev,输出报告 A 命中率 + 报告 B 未收录候选)。
- 修报告 A 失效词条(逐条在新 bundle 中核实):
- 压缩器改了变量名(如
Tt.productName → wt.productName)→ from 和 to 必须同步改(to 里含旧变量名会把未定义标识符写进 bundle,弄坏对应 UI)。
- 文案被官方删除 → 删除该词条,不留死条目。
- 半翻污染修复类条目(from 为 pen-zh 旧版污染态中文)在 pen.dev 全量更新后必然过时 → 删除。
- 筛报告 B 新候选(人工判断):
- 真 UI 文案 → 翻译入库:from 优先带引号断言(
"..."),入库前必须校验 bundle.includes(from),不命中拒绝写盘。
- 跳过:品牌/字体/技术栈名、日志与解析器报错、LLM 提示词模板、AI 模板/风格预设描述、SVG path。
- 本机验证:用
lib/patcher.js 的 applyPatch 应用到当前 pen.dev → 再跑 npm run scan,目标「已应用 N/N、失效 0」。
- 测试与打包:
npm run check + npm test → package.json 升版本号 → npm run package。
- 提交并发版:git commit 词典与版本变更 → 上传 vsix 到 Marketplace(网页或
vsce publish)。
维护注意:
- PowerShell
> 重定向会把 node 输出写成 UTF-16,毁掉报告解析;报告落盘用 execFileSync + fs.writeFileSync。
- 恢复英文依赖
extension.js 的 penzh.disabled 禁用标记(globalState),sweep 会尊重该标记;除非处理 restore 回归,不要动这段逻辑。
scripts/scan.js 只读零副作用,scripts/_filter_ui.js 辅助筛分类2 长句候选。
限制
- 仅覆盖 pen.dev 编辑器 webview 内的文案;VS Code 自身的界面不受本插件影响。
- pen.dev 扩展自身升级时,
out/editor 会被新版覆盖,汉化随之失效;本插件会对该目录做文件监视并周期性心跳检查,识别到资源被覆盖后会自动重新注入中文。若新版新增了未收录的英文文案,个别词条可能仍是英文,重新打开 pen.dev 标签页或运行「pen-zh.refresh」命令补录即可。
- 汉化依赖对当前 bundle 中提取到的字符串;pen.dev 大版本改动 UI 文案后,个别新词条可能暂未收录,按上述方式增补即可。
- 极少数 pen.dev 内置的英文品牌名/技术术语(如
Claude、Codex、模型名)保留原文。
开发与发布
npm test # 单元测试
npm run check # 语法检查
npm run package # 打包 .vsix
npm run publish # 发布到 VS Code MarketPlace(需已注册 publisher 与 PAT)
致谢
本项目基于 0x0Bke/Pencil-ZH(MIT 协议)进行迭代开发,跟随 pen.dev 的版本升级持续更新汉化词条与兼容性。感谢原作者 0x0Bke 提供的初始汉化方案。
License
MIT - 基于 Pencil-ZH 的 MIT 协议
| |