多语言翻译管理
本项目只维护中文 (docs/zh/) 内容,其他语言通过脚本自动翻译生成。
快速参考
| 场景 | 命令 |
|---|---|
| 新增语言 | npx tsx scripts/translate.ts add ja 日本語 --write |
| 删除语言 | npx tsx scripts/translate.ts remove ja --write |
| 全量翻译某语言 | npx tsx scripts/translate.ts en --write |
| 翻译所有语言 | npx tsx scripts/translate.ts --all --write |
| 翻译单个文件 | npx tsx scripts/translate.ts file tutorial/canvas-layers.md en --write |
| 校验文件结构 | npx tsx scripts/translate.ts validate |
| 批量重命名文件 | npx tsx scripts/translate.ts rename --write |
| 预览 (不写入) | 去掉 --write 参数即可 |
环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
OPENAI_API_KEY | API Key | 内置 DeepSeek Key |
OPENAI_BASE_URL | API 地址 | https://api.deepseek.com |
OPENAI_MODEL | 模型名称 | deepseek-v4-flash |
也可以使用 DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL 作为别名。
文件结构
项目根目录/
├── scripts/translate.ts # 翻译脚本
├── docs/
│ ├── zh/ # 中文源文件 (手动维护)
│ │ ├── index.md
│ │ ├── download.md
│ │ ├── tutorial/
│ │ │ ├── canvas-layers.md
│ │ │ └── ...
│ │ ├── privacy.md
│ │ └── ...
│ ├── en/ # 英文 (脚本生成, .gitignore)
│ │ └── ... # 与 zh/ 同结构
│ └── .vitepress/config.ts # VitePress 配置 (脚本自动管理多语言部分)场景详解
1. 新增语言
一键完成:更新配置 → 翻译所有 md → 翻译导航/侧边栏/界面文案 → 注入 config.ts
# 预览
npx tsx scripts/translate.ts add ja 日本語
# 确认后写入
npx tsx scripts/translate.ts add ja 日本語 --write脚本会自动完成:
- 在
config.ts的CONFIGURED_LOCALES中添加ja: '日本語' - 将
docs/zh/下所有 md 翻译到docs/ja/ - 翻译导航栏文本 (首页→ホーム, 下载→ダウンロード 等)
- 翻译侧边栏文本和链接前缀
- 翻译界面文案 (上一页→前へ, 菜单→メニュー 等)
- 将翻译结果注入
config.ts的translatedNavs/translatedSidebars/translatedThemeConfigs
2. 删除语言
完全清除:删除目录 → 删除配置 → 清理 config.ts 注入
# 预览
npx tsx scripts/translate.ts remove ja
# 确认后执行
npx tsx scripts/translate.ts remove ja --write脚本会自动完成:
- 从
config.ts的CONFIGURED_LOCALES删除ja - 删除
docs/ja/整个目录 - 从
config.ts中删除translatedNavs.ja、translatedSidebars.ja、translatedThemeConfigs.ja
3. 全量重新翻译某语言
当中文源文件有大量更新时,重新翻译整个语言:
# 预览 (不会写入文件)
npx tsx scripts/translate.ts en
# 确认后写入
npx tsx scripts/translate.ts en --write这会覆盖 docs/en/ 下所有文件。
4. 翻译单个文件
新增或修改了某个中文文档,不想全量翻译,只翻译这一个文件:
# 翻译教程中的画布与图层页
npx tsx scripts/translate.ts file tutorial/canvas-layers.md en --write
# 翻译首页
npx tsx scripts/translate.ts file index.md en --write
# 翻译隐私协议到所有已配置语言 (需要逐个执行)
npx tsx scripts/translate.ts file privacy.md en --write
npx tsx scripts/translate.ts file privacy.md ja --write路径是相对于 docs/zh/ 的路径。
5. 翻译所有语言
npx tsx scripts/translate.ts --all --write6. 校验翻译完整性
检查所有语言的文件结构和 frontmatter key 是否一致:
npx tsx scripts/translate.ts validate校验内容:
- 目标语言目录是否存在
- 文件列表是否与
docs/zh/一致 (缺少/多余) - 每个文件的 frontmatter key 是否与中文源一致
7. 新增中文页面后更新翻译
- 在
docs/zh/下创建新 md 文件 - 如果是教程页面,在
config.ts的zhSidebar中添加条目 - 翻译单个文件到各语言:bash
npx tsx scripts/translate.ts file new-page.md en --write - 如果新增了导航/侧边栏条目,需要手动在
config.ts的translatedNavs/translatedSidebars中补充对应语言的翻译
8. 批量重命名文件
当 docs/root/tutorial/ 下的文件名需要修改时(如中文文件名改为英文),使用 rename 命令:
# 预览重命名
npx tsx scripts/translate.ts rename
# 确认后写入
npx tsx scripts/translate.ts rename --write重命名映射定义在 scripts/translate.ts 的 FILE_RENAME_MAP 常量中。脚本会:
- 遍历
docs/root/tutorial/和所有语言目录的tutorial/子目录 - 将旧文件名重命名为新文件名
- 已重命名的文件自动跳过
如需新增重命名规则,编辑 FILE_RENAME_MAP 后重新运行即可。
9. 修改已有中文页面后更新翻译
- 修改
docs/zh/下的文件 - 只翻译修改的文件:bash
npx tsx scripts/translate.ts file tutorial/canvas-layers.md en --write
翻译保护机制
参考 Flutter 项目的 i18n_manager.py 设计,翻译脚本内置了以下保护:
PlaceholderProtector
翻译前将敏感内容替换为占位 token (如 WDPROTECT0TOKEN),翻译后还原并校验完整性。
保护内容:
- URL —
https://...不会被翻译 - 邮箱 —
xxx@xxx.com不会被翻译 - 品牌词 —
拼豆圈、Pixel Bead保持不变 - 技术术语 —
PNG、RGB、Android、iOS、PICO-8、DB32等保持不变
如果 AI 破坏了占位 token (改名/删除/拆分),还原时会报错。
Frontmatter 保护
- 只翻译
title、text、tagline、details、description等 key 的值 - key 名称保持不变
- 翻译后校验 key 是否完整 (缺失/多余都会警告)
编码校验
检测翻译结果中是否包含禁止字符 (BOM、零宽空格等)。
Dry run 默认
所有写操作默认只预览,必须加 --write 才实际写入,防止误操作。
重试机制
瞬态错误 (429/502/503/超时) 自动重试 3 次,指数退避。
config.ts 中的多语言区域
config.ts 中由脚本自动管理的区域 (不要手动修改):
CONFIGURED_LOCALES— 已配置的语言列表 (脚本add/remove自动维护)translatedNavs— 各语言的导航栏translatedSidebars— 各语言的侧边栏translatedThemeConfigs— 各语言的界面文案
如果需要调整某个语言的翻译,修改后重新运行 add 命令覆盖即可。
.gitignore 说明
docs/en/、docs/ja/、docs/ko/ 等翻译目录默认在 .gitignore 中,因为它们是自动生成的。
如果需要提交翻译文件到 git (例如确认翻译质量后),使用 git add -f docs/en/ 强制添加。
