Material Maker 本地化翻译工作流完全指南:基于 gettext 的多语言支持体系
Material Maker 本地化翻译工作流完全指南:基于 gettext 的多语言支持体系
Material Maker 是一款基于 Godot 引擎的程序化材质创作与 3D 模型绘制工具,其界面、材质节点与内置材质库均通过一套完整的 gettext 本地化体系实现多语言支持。本文以仓库中 locale/README.md 为骨架,结合 locale 目录 下的实际脚本与翻译文件,系统讲解从环境搭建、翻译创建、模板更新到运行时加载的完整流程,读完后你将掌握为该工具新增一种语言、校验翻译语法、同步模板以及理解本地化运行机制的实战能力。
一、本地化体系概览:locale 目录的角色分工
Material Maker 的本地化文件全部集中在仓库根目录下的 material_maker/locale/,各文件职责如下:
| 文件/目录 | 角色 |
|---|---|
README.md |
本地化工作流说明文档(本文依据) |
create_translation.sh |
一键创建新语言的 PO 翻译文件 |
check.sh |
批量校验所有 .po 文件的语法 |
merge.sh |
将翻译文件与最新模板合并 |
generate_po_template.sh |
调用 pybabel 从源码提取字符串并生成 POT 模板 |
generate_po_template.gd |
Godot EditorScript,负责从场景、脚本、节点、库文件中提取可翻译字符串 |
babelrc |
pybabel 提取器的配置文件(定义文件类型与编码) |
requirements.txt |
pybabel 及其 Godot 扩展的依赖清单 |
locale.gd |
运行时翻译安装与加载逻辑 |
material-maker.pot |
核心界面/脚本字符串模板(约 1028 行) |
material-maker-all.pot |
含预置节点与材质库的全量模板(约 9962 行) |
translations/ |
已翻译的语言文件(fr.csv、fr.po、zh.csv) |
该体系以 GNU gettext 的 POT → PO → 编译/加载 模型为底,并针对 Material Maker 的"节点定义(.mmg)、材质库(.json)、场景(.tscn)"等 Godot 特有资产做了定制化字符串提取,属于 Godot 官方推荐的 Localization using gettext 方案的工程化实现。
二、环境准备:gettext 工具与 pybabel
2.1 安装 gettext 工具
gettext 工具链中的 msginit、msgfmt、msgmerge 分别负责新建翻译、语法校验与模板合并。只有当你需要创建新翻译、检查翻译文件语法或同步模板时才必须安装,纯做翻译审阅无需安装:
- Windows:从 gettext-iconv 官方下载页获取安装包,任意架构与二进制类型(shared 或 static)均可,拿不准时选 64 位 static 安装版即可。
- macOS:先安装 Homebrew,然后执行
brew install gettext。 - Linux:通过发行版自带包管理器安装
gettext(不同发行版包名可能不同,如 Debian/Ubuntu 为gettext)。
2.2 安装 pybabel
此步仅在需要重新生成 PO 模板时必需。作为普通翻译者,通常不需要重新生成模板。要求 Python 3.7 及以上,安装依赖:
pip3 install --user --upgrade -r requirements.txt
其中 requirements.txt 固定了两个关键依赖:
babel==2.9.1
babel-godot==1.0
babel 是 Python 生态标准的 gettext 提取/编译库;babel-godot 则扩展了 Babel,使其能够按 Godot 脚本与场景的语法规则提取字符串。
三、核心翻译工作流:四个标准任务
3.1 创建新翻译
执行 create_translation.sh,并传入语言代码(如 fr、de、es):
./create_translation.sh <language code>
从 create_translation.sh 源码可见,其底层调用的是 gettext 的 msginit,以 material-maker.pot 为输入生成对应语言的 .po 文件:
#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'
cd "$(dirname "${BASH_SOURCE[0]}")"
if [[ "$#" != 1 ]]; then
echo "Usage: $0 <language code>"
echo 'The language code should be of the form "fr", "de", ...'
exit 1
fi
msginit --no-translator --input=material-maker.pot --locale="$1"
脚本要求恰好一个参数,否则会打印用法并退出;--no-translator 跳过交互式翻译者信息录入,便于自动化;生成的 .po 文件头部会带有该语言的 locale 声明(如 "Language: fr")与 Plural-Forms 复数规则,例如仓库中 translations/fr.po 的头部包含:
"Language: fr\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
3.2 校验翻译文件语法
执行 ./check.sh,脚本会遍历 locale 目录下所有 .po 文件,用 msgfmt -c 逐一做严格语法检查:
#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'
cd "$(dirname "${BASH_SOURCE[0]}")"
for po in *.po; do
echo -e "\nChecking syntax in $po..."
msgfmt -c "$po" -o /dev/null
done
msgfmt -c 的 -c(check)模式会报告格式错误、复数形式错误、缺失或多余条目等问题;-o /dev/null 表示只校验不生成二进制结果。如果仓库现有翻译(如 fr.po)需要人工修订后重新校验,此命令即是最快验证手段。
3.3 更新翻译模板(POT)
执行 ./generate_po_template.sh,从全部源码重新提取字符串并生成 material-maker.pot。切勿手动编辑生成的 .pot 文件,因为下次生成模板时所有手工改动都会被覆盖。
脚本先切换到 locale 的上级目录(项目根),再调用 pybabel 提取:
pybabel extract \
-F locale/babelrc \
-k text \
-k LineEdit/placeholder_text \
-k tr \
-o locale/material-maker.pot \
.
参数含义:
-F locale/babelrc:使用 babelrc 作为提取配置,其中声明了两类文件的编码与语法:[python: **.gd] encoding = utf-8 [godot_scene: **.tscn] encoding = utf-8-k text/-k LineEdit/placeholder_text/-k tr:声明需要提取的"关键字",即源码中调用这些函数的字符串参数会被视为可翻译条目。-o locale/material-maker.pot:输出模板路径。.:以当前目录(项目根)为递归搜索起点。
更深一层的定制提取:generate_po_template.gd
pybabel extract 只能覆盖 .gd 脚本中的 tr() 调用与 .tscn 场景中的 text/tooltip_hint 属性。Material Maker 的界面字符串还大量存在于**预置节点定义(.mmg JSON)与材质库(library/*.json)**中,因此 generate_po_template.gd 这个 @tool EditorScript 承担了二次提取与合并工作。它的 _run() 流程(第 348-367 行)分三个阶段:
- 提取场景与脚本:递归扫描
res://下全部.gd/.tscn(跳过addons/gut测试框架),正则提取:.gd:tr("...")调用、菜单名(menu="...")、面板名(name="..."...scene=);.tscn:text与tooltip_hint属性,以及TabContainer下的节点名;- 结果保存为
material-maker.pot。
- 提取预置节点:解析
addons/material_maker下所有.mmg(JSON),按type分类提取:graph类型:label、shortdesc、longdesc,以及gen_parameters节点的控件名/描述、gen_inputs/gen_outputs端口字段;material_export/shader/brush类型:shader_model的name、shortdesc、longdesc,以及参数、输入、输出字段与枚举values的名称;
- 提取材质库:解析
material_maker/library下所有.json,提取库名name与tree_item的层级片段(即素材库树形目录的每一级名称)。
最终把阶段 2、3 的条目并入,另存为全量模板 material-maker-all.pot。这也解释了为什么仓库同时存在两个 POT:material-maker.pot(约 1028 行,核心界面)与 material-maker-all.pot(约 9962 行,含全部节点与材质库)。
提取完成后,脚本还会把 translations/ 下已有的 .po/.csv 翻译按新模板重新导出为 csv 格式,并生成 .report 文件,列出每个语言文件的缺失字符串(Missing strings)与多余字符串(Extra strings)(见 generate_po_template.gd),方便翻译者定位漏译与废弃条目。
3.4 合并更新既有翻译
当模板新增或修改了字符串后,执行 ./merge.sh 将每个 .po 文件与 material-maker.pot 合并:
msgmerge -w 79 -C "$po" "$po" material-maker.pot > "$po".new
mv -f "$po".new "$po"
-w 79:将合并输出按 79 列宽度折行,保持格式整洁;-C "$po":把旧文件作为"此前翻译"的参考,尽量保留已有译文;- 合并结果先写入
$po.new再原子替换原文件。
合并后,新增的字符串会被自动加入,被修改的字符串会带有 fuzzy 标记。翻译者必须逐个审查带 fuzzy 的条目,确认译文无误后移除该标记,否则该条目不会在运行时生效。
四、翻译文件格式与仓库现状
4.1 两种格式:PO 与 CSV
仓库的 translations/ 目录同时维护着两种格式的翻译:
- PO 格式(如 translations/fr.po,约 429 行):gettext 标准格式,条目形如:
每个条目附带来源引用(#: main_window.tscn:103 msgid "File" msgstr "Fichier"#:行),便于定位字符串出处。 - CSV 格式(如 translations/fr.csv、translations/zh.csv):首行为
id|<language code>头,后续每行原文|译文一一对应,如中文翻译File|文件、New material|新建材质。CSV 是 Material Maker 运行时优先采用的轻量格式,zh.csv共约 1745 行,覆盖了主要菜单与界面文案。
generate_po_template.gd 的 read_language_file(第 33-76 行)支持按扩展名识别输入:.po 直接通过 Godot 的 load() 载入 Translation 资源,.csv 则用 read_language_file_csv(第 78-108 行)手动解析——它会从首行探测分隔符,处理带引号的字段,并把转义的 \n 还原为换行,同时统计提取出的字符串数量。
4.2 POT 模板结构
material-maker.pot 头部包含标准的 gettext 元信息(Project-Id-Version、POT-Creation-Date、Content-Type: text/plain; charset=utf-8 等),随后是形如:
#: res:///start.tscn:82
#: res:///material_maker/windows/about/about.tscn:76
msgid "Material Maker"
msgstr ""
的条目——msgstr 为空表示待翻译,#: 行记录字符串在源码中的精确位置(文件 + 行号)。模板中还包含 Menu in ...、Panel name in ... 这类 Material Maker 自定义来源标注,对应 generate_po_template.gd 中从代码提取菜单/面板名称的逻辑(第 199-209 行)。
五、运行时加载机制:locale.gd 与偏好设置集成
翻译文件编译/校验完成后,最终要进入应用运行。Material Maker 采用"用户目录动态加载"方案,核心是 locale.gd:
get_translations_dir()/create_translations_dir():约定翻译目录为user://locale(Godot 用户数据目录,随平台而异),并负责创建;install_translation(fn):把外部传入的翻译文件(.po/.position/.csv)复制到user://locale,随后立即调用read_translations()热加载;uninstall_translation(tn):按语言名删除user://locale下对应语言的三种扩展名文件;read_translations()(第 25-73 行):扫描user://locale目录——.po/.position文件通过load()载入 GodotTranslation资源,按locale属性归并到对应语言并注册进TranslationServer;.csv文件则手动解析:读取id|<lang>头、识别分隔符、逐行将原文|译文写入语言 Translation;其中en列被视为英文基准而跳过注册。
该运行时逻辑被偏好设置界面直接调用。在 windows/preferences/preferences.gd 中:
_on_InstallLanguage_pressed()(第 46-56 行):弹出文件对话框,过滤条件为*.po,*.position,*.csv;Translation file,选中文件后调用locale.install_translation(files[0])完成安装并刷新语言列表——普通用户无需接触命令行即可导入翻译;_on_DownloadLanguage_closed()(第 67-70 行):从网站下载语言包后调用locale.read_translations()重新扫描加载。
此外 project.godot 中 [locale] 段为 translations=PackedStringArray()(运行时翻译全部来自用户目录动态注册),[internationalization] 段设置了 rendering/root_node_layout_direction=1 以适配从右到左的语言排版方向。
六、端到端实战:为 Material Maker 新增一种语言
综合上述机制,一个完整的新语言贡献流程如下:
- 准备环境:按第二节安装 gettext 工具链与 pybabel(
pip3 install --user --upgrade -r requirements.txt)。 - 创建翻译:在
material_maker/locale/目录执行./create_translation.sh <code>(如./create_translation.sh de),生成<code>.po。 - 翻译条目:编辑生成的
.po文件,将每个msgid对应的msgstr填上目标语言译文;翻译后可用./check.sh校验语法,确认无msgfmt -c报错。 - 跟进模板更新(开发者职责):上游改动源码后,运行
./generate_po_template.sh重新生成material-maker.pot与material-maker-all.pot,再运行./merge.sh把新字符串并入各.po;随后逐条审查fuzzy标记的条目并移除标记。 - 发布与安装:把校验通过的
.po或转换后的.csv提供给用户,用户在偏好设置界面通过"Install Language"按钮选择文件,即可写入user://locale并即时生效,无需重新编译程序。
七、小结
Material Maker 的本地化体系是一条"pybabel 提取(脚本/场景)+ Godot 定制提取(节点/材质库)→ POT 模板 → msginit/msgmerge 维护 PO → msgfmt 校验 → user://locale 运行时加载"的完整链路。它不仅覆盖了常规的界面文案,还通过 generate_po_template.gd 深入到了 .mmg 预置节点与材质库 JSON 的描述字段,保证了材质节点名称、参数说明也能随语言切换。掌握这套工作流后,无论是为项目贡献新语言、审校既有翻译,还是理解 Godot 应用中 gettext 落地的工程模式,都可以以此为参考模板。