解剖 Zed 汉化工具链:zed-globalization 的 zedl10n 七大子命令全流程图解
解剖 Zed 汉化工具链:zed-globalization 的 zedl10n 七大子命令全流程图解
Zed 汉化工具链 zed-globalization 是一款 AI 驱动的 Zed 编辑器多语言本地化项目,内置的 zedl10n 命令行工具通过 scan、extract、translate、replace、fix-placeholders、convert、pipeline 七大子命令,把 Zed 源码界面自动翻译成简体中文、繁体中文、日语、韩语。
一张图看懂:Zed 汉化流水线全景
整个汉化流程是一条「AI 驱动全自动翻译构建」流水线,每个子命令负责一个环节:
Zed Rust 源码
│
├─ 1. scan AI 判断哪些 .rs 文件含 UI 文案(支持增量)
├─ 2. extract 正则提取字符串 + 收集代码上下文
├─ 3. translate AI 并发翻译(三级降级 + 术语表约束)
├─ 4. fix-placeholders AI 修复占位符不匹配的译文
├─ 5. replace 译文替换回源码(三层编译保护)
└─ 6. pipeline 一键串联 extract → translate
│
▼
i18n/zh-CN.json 译文文件
│ 7. convert JSON ↔ Excel 双向转换,人工校对
▼
cargo build 编译 → 跨平台安装包(Windows / Linux / macOS)
zedl10n 的 CLI 入口定义在 src/zedl10n/cli.py,命令由 pyproject.toml 注册,pip install ".[all]" 之后即可在终端直接使用。
zedl10n 七大子命令速查表
| 子命令 | 一句话职责 | 是否调用 AI | 核心源码 |
|---|---|---|---|
scan |
AI 识别需翻译的 .rs 文件 | ✅ | scan.py |
extract |
提取字符串 + 上下文 | ❌ | extract.py |
translate |
AI 并发翻译 | ✅ | translate.py |
replace |
替换 Zed 源码字符串 | ❌ | replace.py |
fix-placeholders |
修复占位符错误译文 | ✅ | fix_placeholders.py |
convert |
JSON ↔ Excel 互转 | ❌ | convert.py |
pipeline |
一键流水线 | ✅ | cli.py |
1. scan —— 快速扫描:AI 找出哪些文件需要汉化
zedl10n scan --source-root zed 会递归遍历 Zed 源码的 crates/ 目录,把每个 .rs 文件交给 AI 判断:是包含菜单、按钮、提示语等面向用户的字符串,还是只有内部标识符、日志、测试断言? AI 只需回答 YES/NO。
几个新手需要知道的设计细节:
- 超大文件会被自动切成多段送审,避免超出模型上下文;
- 支持增量扫描:提供上次
scan_result.json加上变化/删除文件列表,只需分析改动部分,省时省 token; - 判定提示词直接写在 scan.py 中,可以清楚看到判断标准。
2. extract —— 一键提取字符串:正则 + 上下文收集
zedl10n extract --source-root zed --output string.json
这一步不调用 AI:extract.py 用正则匹配所有双引号字符串(自动排除 json_path: 之类的干扰行),同时为每条字符串收集前后 3 行代码上下文,输出两个文件:
string.json—— 文件 → 原文列表的映射;string_context.json—— 每条字符串对应的代码片段,后续让 AI「看懂」字符串用途。
上下文是翻译质量的关键:同一个单词 "Terminal",在按钮文案里要译成「终端」,在 key_context.add("Terminal") 里就必须保留原样。
3. translate —— AI 并发翻译:三级降级 + 术语表
zedl10n translate --input string.json --output i18n/zh-CN.json --mode full
这是整条工具链的心脏,translate.py 有几个值得新手了解的保护机制:
- 三级降级解析:AI 返回先按 JSON 解析,失败降级为 XML CDATA,再失败降级为编号列表——三级各重试 3 次,大幅降低解析失败率;
- 流式保活:大批次翻译时采用流式请求,chunk 持续到达可证明连接存活,防止代理层因空闲超时掐断 5~10 分钟的长请求(逻辑见 translate.py);
- 术语表约束:config/glossary.yaml 定义了
workspace → 工作区、hunk → 代码块等 100+ 条术语,保证全文译名统一; - 占位符铁律:
{name}、{:?}等占位符必须原样保留、顺序不变,严禁把 ASCII 标点改成中文标点(规则见 prompts.py)。
--mode incremental 增量模式只翻译新增/变更条目,配合 AI 并发参数(--concurrency)可显著降低成本。
4. replace —— 把译文写回源码的「三层保护」
zedl10n replace --input i18n/zh-CN.json --source-root zed
replace.py 负责最危险的一步——直接修改 Rust 源码。它内置三层保护,确保替换后一定还能编译:
- 翻译过滤:跳过纯标点、纯小写标识符,避免破坏数组与匹配语法;
- 受保护区域:字节串、原始字符串(正则/shell 模式)、
#<a href="https://link.gitcode.com/i/658371772d3a21e91a3b36f71e2495ce" target="_blank">action(...)]属性宏、keymap 上下文等一律跳过(保护规则定义在 [replace.py); - 语法修正:译文中的双引号自动转义,字符串之间被误改的中文标点还原为 ASCII。
替换前还会逐条校验占位符:位置绑定的 {} 顺序必须严格一致,命名的 {name} 只需集合相同。
5. fix-placeholders —— AI 占位符修复器
AI 偶尔会「好心」调整译文里的占位符,导致与原文不匹配。zedl10n fix-placeholders 会扫出这些坏条目,逐条交给 AI 重写,并用同一套占位符校验函数复核,最多重试 3 次(实现见 fix_placeholders.py)。
6. convert —— 人工校对友好:JSON 与 Excel 双向转换
纯 AI 翻译难免需要人工把关。convert 提供两个方向:
zedl10n convert to_excel --json i18n/zh-CN.json
# 在 Excel 中修改「译文」列后
zedl10n convert to_json --json i18n/zh-CN.json --excel 校对后.xlsx
生成的表格包含「文件路径 / 原文 / 译文 / 状态」四列,非程序员也能直接参与校对(转换逻辑见 convert.py)。
7. pipeline —— 一键流水线:一条命令跑完主流程
分步执行适合理解原理,日常使用一条命令即可:
zedl10n pipeline --source-root zed --lang zh-CN --mode full
pipeline 的实现 串联「字符串提取 → AI 翻译」两个阶段,自动收集所有 .rs 文件并输出 i18n/zh-CN.json,全程打印耗时统计。
质量辅助三件套:让汉化更稳
除了七大主力子命令,cli.py 还注册了三个质量保障命令:
| 子命令 | 作用 |
|---|---|
mark-untranslatable |
用保守规则 + AI 判定「确定无需翻译」的条目,写入禁翻清单 config/do_not_translate.json ,避免增量轮次反复重翻空值 |
consistency |
跨文件术语不一致检查,--fix 可依据术语表自动修复覆盖写入 |
release-notes |
拉取并翻译 Zed 官方 Release Notes,生成带版本头的中文发布说明 |
本地跑一遍:Zed 汉化版构建步骤
想自己构建 Zed 汉化版(ZedG)只需四步:
- 克隆 Zed 官方源码到
./zed目录; - 安装工具链:
pip install ".[all]",并配置 AI 环境变量AI_BASE_URL、AI_API_KEY、AI_MODEL(支持任何 OpenAI 兼容 API,默认gpt-4o-mini); - 运行
zedl10n pipeline --source-root zed --lang zh-CN --mode full生成译文,再用zedl10n replace替换源码; cargo build --release编译,即可得到中文界面。
完整说明参见 README.md 与自动化流水线部分。
常见问题:为什么 zedl10n 要设计这么多子命令?
- 为什么要单独 scan? AI 先筛文件,避免对纯逻辑代码浪费翻译 token;
- 为什么要 collect 上下文? 让 AI 区分「用户可见文案」和「代码标识符」,这是少翻错的关键;
- 为什么要三层降级 + 保护? 目标是替换后 Rust 代码 100% 可编译,任何一环出错都有兜底;
- 为什么有 pipeline? 日常迭代只需一条命令,分步子命令留给排错与定制。
写在最后:Zed 汉化项目的技术亮点
zed-globalization 把「AI 翻译」做成了工程问题:扫描有增量、翻译有降级、替换有保护、术语有表格、校对有 Excel、质量有检查。这套 zedl10n 工具链的模式,同样适用于任何 Rust 大型项目的多语言化,值得本地化工程师参考。
💡 本文基于仓库当前版本的源码整理,各子命令的最新参数请以
zedl10n --help输出为准。