如何为Blender Launcher V2添加新语言：i18n本地化工作流程完整教程

如何为Blender Launcher V2添加新语言：i18n本地化工作流程完整教程

【免费下载链接】Blender-Launcher-V2Standalone client for managing official builds of Blender 3D and its popular forks项目地址: https://gitcode.com/gh_mirrors/bl/Blender-Launcher-V2

Blender Launcher V2 是一个开源的独立客户端，用于管理 Blender 3D 官方构建版本及其流行衍生分支（Fork）的下载与启动。本文是一份面向新手的i18n 本地化完整指南，教你如何用 6 个步骤为 Blender Launcher V2 添加新语言支持——只需复制 YAML 翻译文件、在Language枚举中注册语言，再运行覆盖率脚本验证，全程不需要修改业务代码。

一、认识 Blender Launcher V2 的国际化架构 🌐

在动手翻译之前，先理解三件事，整个本地化流程就会一目了然：

目前项目已内置英语（en）、西班牙语（es）、法语（fr）、日语（ja）、中文（zh）五种语言。以中文为例，localization/目录下的settings.zh.yml、wizard.zh.yml、msg.zh.yml等文件就分别对应设置页、新手引导、消息提示等不同界面模块的翻译。

程序中的调用方式统一为t("命名空间.键名")，例如在 general_tab.py 中，语言下拉框的标题就来自settings.general.app.language这个 key——这正是你翻译时需要在 YAML 里提供的内容。

二、准备工作：克隆仓库并运行项目 ⚙️

1. 克隆代码仓库

git clone https://gitcode.com/gh_mirrors/bl/Blender-Launcher-V2

2. 安装依赖并运行

项目使用uv管理依赖（依赖清单见 uv.lock），安装后通过 Makefile 一键启动：

make run

该命令会先执行build_style.py生成样式资源，再启动 main.py。首次运行会弹出新手引导向导，语言设置位于设置 → 常规（General）页面的"语言"下拉框中，支持 Auto 自动检测系统语言。

三、6 步添加新语言的完整工作流程 ✍️

💡 官方文档 localization.md 中 "Contributing Translations" 章节也详细描述了该流程，建议配合阅读。

第 1 步：复制一份现有翻译文件（不要从零新建）

以添加德语（de）为例，把每个命名空间的英文或中文文件复制一份，并将文件名中的语言标签改为de：

source/resources/localization/ ├── settings.en.yml → settings.de.yml ├── wizard.en.yml → wizard.de.yml ├── msg.en.yml → msg.de.yml ├── repo.en.yml → repo.de.yml ├── act.en.yml → act.de.yml ├── launching.en.yml → launching.de.yml └── custom_build.en.yml → custom_build.de.yml

为什么必须复制而不是新建？官方文档明确指出：保持各语言文件的 key 顺序一致，能让后续版本更新时更容易对照，也方便覆盖率脚本准确比对。

第 2 步：翻译内容，严守"key 不可变"原则

打开复制出的settings.de.yml，逐条把英文值翻译成目标语言。唯一不能动的就是 key——一旦 key 与英文基准对不上，程序就找不到对应翻译，界面会自动回退显示英语。

第 3 步：遵守两条 YAML 书写约定 📝

• 含冒号的字符串必须加双引号：YAML 把:解析为键值分隔符，所以值里出现冒号时必须整体加引号：

  example_string: "Time: 10:30 AM"

• 多行文本优先使用块标量|，而不是在一行里塞\n；提示框（tooltip）应紧跟在其所属 key 下方：

  key: Some string in our program key_tooltip: | This is a multiline tooltip explaining something. It can span several lines for detailed information.

第 4 步：善用模板变量与复数功能

python-i18n提供了两个实用特性，翻译时只需保留占位符格式即可：

• 模板变量：用%{name}形式嵌入动态内容，例如"You have %{item_count} items in your cart."，翻译后写成Dein Warenkorb enthält %{item_count} Artikel.

• 复数处理：当传入count参数时，会自动匹配zero/one/many子键，缺省时回退到many：

  files_downloaded: zero: No files downloaded yet. one: 1 file downloaded. many: "%{count} files downloaded."

第 5 步：在 Language 枚举中注册新语言

如果该语言在项目中完全不存在（本例中的德语），需要编辑 i18n_init.py，在Language枚举中添加成员，并在display_name映射里补充该语言的显示名：

class Language(StrEnum): AUTO = "auto" ENGLISH = "en" ... GERMAN = "de" # ← 新增语言代码 @property def display_name(self) -> str: names = { ... Language.GERMAN: "Deutsch", # ← 新增显示名 } return names[self]

这一步会让新语言出现在设置 → 常规 → 语言下拉菜单中（界面见下方截图）。

第 6 步：用覆盖率脚本检查翻译进度 ✅

项目自带language_coverage.py脚本，可对翻译进度进行量化验收：

# 查看所有语言的覆盖率汇总 python scripts/language_coverage.py # 只查看德语的进度，并自动列出缺失的 key python scripts/language_coverage.py --language de # 列出所有语言的缺失 key 明细 python scripts/language_coverage.py --list-missing-keys

脚本会以英文为基准，输出每个命名空间的翻译百分比、总覆盖率排名表，以及按语言分组的缺失 key 清单——这就是你提交前的"验收报告"。

四、验证与提交 🚀

1. 运行make run启动应用，在设置 → 常规 → 语言中选择新语言（切换语言需要重启应用才能生效，这一点在设置页的 tooltip 中也有说明）。
2. 逐页浏览主窗口、设置、新手引导向导，确认界面无英语残留（个别漏翻会自动回退成英文，属正常现象，可继续补全）。
3. 覆盖率脚本显示目标语言覆盖率达标后，即可发起 PR——官方文档明确表示"热烈欢迎引入新语言支持的贡献"。

常见坑点速查表

五、总结 📌

为 Blender Launcher V2 添加新语言的核心流程可以浓缩为一句话：复制 YAML → 翻译（key 不动）→ 注册枚举 → 覆盖率验收。整个工作只涉及source/resources/localization/下的翻译文件和 i18n_init.py 一处枚举注册，配合language_coverage.py的量化反馈，即使你是第一次参与开源本地化，也能在半天内完成一种语言的高质量翻译。快去把界面变成你的母语吧！

【免费下载链接】Blender-Launcher-V2Standalone client for managing official builds of Blender 3D and its popular forks项目地址: https://gitcode.com/gh_mirrors/bl/Blender-Launcher-V2