Material Maker 本地化翻译工作流完全指南:基于 gettext 的多语言支持体系

原创2026-10-11 21:11:221,976 阅读
文章标签:桌面应用图像处理3D建模图形学

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 行)分三个阶段:

  1. 提取场景与脚本:递归扫描 res:// 下全部 .gd/.tscn(跳过 addons/gut 测试框架),正则提取:
    • .gd:tr("...") 调用、菜单名(menu="...")、面板名(name="..."...scene=);
    • .tscn:text 与 tooltip_hint 属性,以及 TabContainer 下的节点名;
    • 结果保存为 material-maker.pot。
  2. 提取预置节点:解析 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 的名称;
  3. 提取材质库:解析 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() 载入 Godot Translation 资源,按 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 新增一种语言

综合上述机制,一个完整的新语言贡献流程如下:

  1. 准备环境:按第二节安装 gettext 工具链与 pybabel(pip3 install --user --upgrade -r requirements.txt)。
  2. 创建翻译:在 material_maker/locale/ 目录执行 ./create_translation.sh <code>(如 ./create_translation.sh de),生成 <code>.po。
  3. 翻译条目:编辑生成的 .po 文件,将每个 msgid 对应的 msgstr 填上目标语言译文;翻译后可用 ./check.sh 校验语法,确认无 msgfmt -c 报错。
  4. 跟进模板更新(开发者职责):上游改动源码后,运行 ./generate_po_template.sh 重新生成 material-maker.pot 与 material-maker-all.pot,再运行 ./merge.sh 把新字符串并入各 .po;随后逐条审查 fuzzy 标记的条目并移除标记。
  5. 发布与安装:把校验通过的 .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 落地的工程模式,都可以以此为参考模板。

登录后查看全文
material-maker