Skip to content

多语言翻译管理 ​

本项目只维护中文 (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_KEYAPI Key内置 DeepSeek Key
OPENAI_BASE_URLAPI 地址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

bash
# 预览
npx tsx scripts/translate.ts add ja 日本語

# 确认后写入
npx tsx scripts/translate.ts add ja 日本語 --write

脚本会自动完成:

  1. 在 config.ts 的 CONFIGURED_LOCALES 中添加 ja: '日本語'
  2. 将 docs/zh/ 下所有 md 翻译到 docs/ja/
  3. 翻译导航栏文本 (首页→ホーム, 下载→ダウンロード 等)
  4. 翻译侧边栏文本和链接前缀
  5. 翻译界面文案 (上一页→前へ, 菜单→メニュー 等)
  6. 将翻译结果注入 config.ts 的 translatedNavs/translatedSidebars/translatedThemeConfigs

2. 删除语言 ​

完全清除:删除目录 → 删除配置 → 清理 config.ts 注入

bash
# 预览
npx tsx scripts/translate.ts remove ja

# 确认后执行
npx tsx scripts/translate.ts remove ja --write

脚本会自动完成:

  1. 从 config.ts 的 CONFIGURED_LOCALES 删除 ja
  2. 删除 docs/ja/ 整个目录
  3. 从 config.ts 中删除 translatedNavs.ja、translatedSidebars.ja、translatedThemeConfigs.ja

3. 全量重新翻译某语言 ​

当中文源文件有大量更新时,重新翻译整个语言:

bash
# 预览 (不会写入文件)
npx tsx scripts/translate.ts en

# 确认后写入
npx tsx scripts/translate.ts en --write

这会覆盖 docs/en/ 下所有文件。

4. 翻译单个文件 ​

新增或修改了某个中文文档,不想全量翻译,只翻译这一个文件:

bash
# 翻译教程中的画布与图层页
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. 翻译所有语言 ​

bash
npx tsx scripts/translate.ts --all --write

6. 校验翻译完整性 ​

检查所有语言的文件结构和 frontmatter key 是否一致:

bash
npx tsx scripts/translate.ts validate

校验内容:

  • 目标语言目录是否存在
  • 文件列表是否与 docs/zh/ 一致 (缺少/多余)
  • 每个文件的 frontmatter key 是否与中文源一致

7. 新增中文页面后更新翻译 ​

  1. 在 docs/zh/ 下创建新 md 文件
  2. 如果是教程页面,在 config.ts 的 zhSidebar 中添加条目
  3. 翻译单个文件到各语言:
    bash
    npx tsx scripts/translate.ts file new-page.md en --write
  4. 如果新增了导航/侧边栏条目,需要手动在 config.ts 的 translatedNavs/translatedSidebars 中补充对应语言的翻译

8. 批量重命名文件 ​

当 docs/root/tutorial/ 下的文件名需要修改时(如中文文件名改为英文),使用 rename 命令:

bash
# 预览重命名
npx tsx scripts/translate.ts rename

# 确认后写入
npx tsx scripts/translate.ts rename --write

重命名映射定义在 scripts/translate.ts 的 FILE_RENAME_MAP 常量中。脚本会:

  1. 遍历 docs/root/tutorial/ 和所有语言目录的 tutorial/ 子目录
  2. 将旧文件名重命名为新文件名
  3. 已重命名的文件自动跳过

如需新增重命名规则,编辑 FILE_RENAME_MAP 后重新运行即可。

9. 修改已有中文页面后更新翻译 ​

  1. 修改 docs/zh/ 下的文件
  2. 只翻译修改的文件:
    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/ 强制添加。

最后更新于:

拼豆圈 | 拼豆作品、任务与豆仓管理