解剖 Zed 汉化工具链:zed-globalization 的 zedl10n 七大子命令全流程图解

原创2026-10-15 10:46:252,521 阅读
文章标签:国际化AI 应用开发工具

解剖 Zed 汉化工具链:zed-globalization 的 zedl10n 七大子命令全流程图解

Zed 汉化工具链 zed-globalization 是一款 AI 驱动的 Zed 编辑器多语言本地化项目,内置的 zedl10n 命令行工具通过 scan、extract、translate、replace、fix-placeholders、convert、pipeline 七大子命令,把 Zed 源码界面自动翻译成简体中文、繁体中文、日语、韩语。

Zed 编辑器应用图标:zed-globalization 汉化版 ZedG 的界面图标

一张图看懂: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 源码。它内置三层保护,确保替换后一定还能编译:

  1. 翻译过滤:跳过纯标点、纯小写标识符,避免破坏数组与匹配语法;
  2. 受保护区域:字节串、原始字符串(正则/shell 模式)、#<a href="https://link.gitcode.com/i/658371772d3a21e91a3b36f71e2495ce" target="_blank">action(...)] 属性宏、keymap 上下文等一律跳过(保护规则定义在 [replace.py);
  3. 语法修正:译文中的双引号自动转义,字符串之间被误改的中文标点还原为 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)只需四步:

  1. 克隆 Zed 官方源码到 ./zed 目录;
  2. 安装工具链:pip install ".[all]",并配置 AI 环境变量 AI_BASE_URL、AI_API_KEY、AI_MODEL(支持任何 OpenAI 兼容 API,默认 gpt-4o-mini);
  3. 运行 zedl10n pipeline --source-root zed --lang zh-CN --mode full 生成译文,再用 zedl10n replace 替换源码;
  4. cargo build --release 编译,即可得到中文界面。

完整说明参见 README.md 与自动化流水线部分。

常见问题:为什么 zedl10n 要设计这么多子命令?

  • 为什么要单独 scan? AI 先筛文件,避免对纯逻辑代码浪费翻译 token;
  • 为什么要 collect 上下文? 让 AI 区分「用户可见文案」和「代码标识符」,这是少翻错的关键;
  • 为什么要三层降级 + 保护? 目标是替换后 Rust 代码 100% 可编译,任何一环出错都有兜底;
  • 为什么有 pipeline? 日常迭代只需一条命令,分步子命令留给排错与定制。

写在最后:Zed 汉化项目的技术亮点

zed-globalization 把「AI 翻译」做成了工程问题:扫描有增量、翻译有降级、替换有保护、术语有表格、校对有 Excel、质量有检查。这套 zedl10n 工具链的模式,同样适用于任何 Rust 大型项目的多语言化,值得本地化工程师参考。

💡 本文基于仓库当前版本的源码整理,各子命令的最新参数请以 zedl10n --help 输出为准。

登录后查看全文
zed-globalization