goldendict-ng 本地化指南:locale 目录翻译文件命名与语言区域代码规范
goldendict-ng 本地化指南:locale 目录翻译文件命名与语言区域代码规范
导读
goldendict-ng 是一款支持多语言界面(UI)的开源词典软件,其全部界面翻译以 Qt 标准 .ts 文件的形式存放在仓库的 locale/ 目录中,由 CMake 构建系统统一编译为运行时加载的 .qm 二进制翻译文件。本文以 locale/README.md 为骨架,系统讲解该项目翻译文件的核心命名规范——避免将区域代码与语言混为一谈、主方言省略区域代码以让系统自动检测生效,并结合 src/main.cc、src/config.cc 与 CMakeLists.txt 中的源码实现,说明这套规范背后的加载机制与实战影响。读完本文,你将掌握:如何判断一个语言变体该不该加区域后缀、goldendict-ng 在何种条件下使用系统自动检测、何种条件下按文件名显式加载翻译,以及如何为该项目新增或维护一个语言文件。
一、locale 目录:仓库中的翻译文件仓库
goldendict-ng 的全部界面翻译集中在 locale/ 目录下,采用 Qt Linguist 的 .ts(Translation Source)格式,每个文件对应一种界面语言。从当前仓库实际内容看,该目录包含 40 余个语言文件,覆盖亚洲、欧洲、非洲与跨区域语言,例如:
- 东亚语言:
zh_CN.ts、zh_TW.ts、ja.ts、ko.ts、vi.ts - 欧洲主流语言:
de.ts、fr.ts、es.ts、pt.ts、it.ts、ru.ts、uk.ts - 其他语系:
ar.ts、fa.ts、hi.ts、tr.ts、eo.ts(世界语)等
其中有一批文件特别值得注意,它们带有下划线分隔的区域代码后缀:
| 语言文件 | 含义 |
|---|---|
es.ts |
卡斯蒂利亚/半岛西班牙语(Peninsular Spanish) |
es_AR.ts |
阿根廷西班牙语 |
es_BO.ts |
玻利维亚西班牙语 |
pt.ts |
欧洲葡萄牙语(European Portuguese) |
pt_BR.ts |
巴西葡萄牙语 |
de.ts |
标准德语(Standard German) |
de_CH.ts |
瑞士德语 |
zh_CN.ts |
简体中文(中国大陆) |
zh_TW.ts |
繁体中文(台湾地区) |
这套"语言 + 区域后缀"的命名格局,正是 locale/README.md 所规定的核心规范在仓库中的直接体现。
二、核心规范一:避免将区域代码与语言关联
locale/README.md 的第一条规则是:Avoid associating region code with languages(不要将区域代码与语言混为一谈)。
这句话的含义可以从两个层面理解:
- 命名语义层面:
.ts文件名的"主字段"应当表达语言本身(language),而非某个政治/地理区域(region/country)。例如语言代码es代表"西班牙语"这一语言,而不是"西班牙这个国家"。把它命名为es_ES虽然也能工作,但语义上把"语言"与"国家"绑定死了——事实上全球有超过 20 个国家以西班牙语为官方语言。 - 加载匹配层面:Qt 的
QTranslator与QLocale在自动匹配翻译文件时,会同时考察语言代码(如es)与语言-区域组合(如es_MX)。如果某语言文件被人为绑定了区域后缀,那么当用户系统区域与该后缀不一致时,自动检测就会失配,翻译加载失败。
这一条是后面"主方言省略区域代码"规则的理论基础:区域信息是 Qt 自动检测机制的输入条件,而不是翻译文件本身应该携带的限定属性。
三、核心规范二:主方言省略区域代码,让自动检测生效
locale/README.md 的第二条规则是:For languages with various dialects, omit region code for the main dialect, so that auto-detection may just work(对于有多种方言的语言,主方言应省略区域代码,这样自动检测就可以直接生效)。
规则的精髓在于:把"无区域后缀"的裸语言文件留给主方言,让 Qt 的区域匹配机制在检测到任何同一语言的区域变体时,都能回退命中该裸语言文件;而那些与主方言差异较大、需要专门维护的次要方言,才附加区域后缀单独成文件。
文档给出了三个官方例证,仓库中可逐一验证:
es.ts是半岛西班牙语(Peninsular Spanish),即西班牙本土通行的卡斯蒂利亚西班牙语。作为西班牙语的默认/主方言,它不带区域后缀;拉美变体则各自成文件(es_AR.ts阿根廷、es_BO.ts玻利维亚)。pt.ts是欧洲葡萄牙语(European Portuguese),作为葡萄牙语主方言不带区域后缀;而用户量庞大的巴西变体单独维护为pt_BR.ts。de.ts是标准德语(Standard German),不带区域后缀;瑞士德语作为差异明显的区域变体单独维护为de_CH.ts。
从 Qt 行为可以推断这套规则的动机:当系统语言环境为 es_MX(墨西哥西班牙语)时,QLocale 机制会按语言优先、区域其次的顺序寻找翻译;裸文件 es.ts 可以在语言层级直接命中,从而"自动检测即可工作"。反之,若主方言文件被命名为 es_ES.ts,则墨西哥、智利等大量西班牙语用户的系统区域都无法匹配到它,自动检测就会失效,这也是文档强调"may just work"的原因。
中文是这条规则的一个特殊案例:简体与繁体在书写系统上差异极大,无法只靠一个 zh.ts 承载,因此仓库分别维护 zh_CN.ts 与 zh_TW.ts 两个区域变体,而非设一个裸 zh.ts 主文件——这也说明"省略区域代码"的前提是该语言的书写系统与词汇差异可以被同一份翻译覆盖。
四、源码视角:翻译加载机制如何印证命名规范
命名规范并非空泛约定,它直接对接 src/main.cc 中启动阶段的翻译加载逻辑。这段代码完整展示了 goldendict-ng 的两种加载路径:
路径一:系统自动检测(interfaceLanguage 为空时)
if ( cfg.preferences.interfaceLanguage.isEmpty() ) {
loaded = loadTranslation_qlocale( *gd_ts, QString(), QString(), Config::getLocDir() );
}
其中 loadTranslation_qlocale 的核心是 qtranslator.load( QLocale(), filename, prefix, directory )——注意第一个参数传入的是当前系统 QLocale(),即让 Qt 依据用户系统区域设置(QLocale().uiLanguages())自行挑选最合适的 .qm 文件。源码注释对此有明确说明(src/main.cc):
If interfaceLanguage is explicitly set, uses filename-based loading, because GD have more languages than Qt & its locale database. If not, then let Qt's qlocale mechanism decide which one to use, because "locale" handling is different in all 3 platforms.
路径二:文件名显式加载(interfaceLanguage 非空且非 "en" 时)
else if ( cfg.preferences.interfaceLanguage != "en" ) {
loaded = gd_ts->load( cfg.preferences.interfaceLanguage, Config::getLocDir() );
}
也就是说,当用户在设置中显式指定了界面语言(配置项 interfaceLanguage,参见 src/config.hh 中"Empty value corresponds to system default"的注释),程序就直接按 <语言代码>.qm 的文件名精确加载;只有当该配置为空(跟随系统)时,才走 QLocale 自动检测。
这正解释了为什么命名规范如此重要:
- 走文件名加载路径时,
es、pt、de这类裸语言名必须是确定的、唯一的——它代表该语言所有用户共享的主方言翻译; - 走自动检测路径时,裸语言文件是 Qt 回退匹配的兜底目标——系统区域为任何该语言变体的用户都能命中。
此外,加载成功后程序还会对 Qt 内置翻译(qt_*)与 WebEngine 翻译(qtwebengine_*)做语言一致性校验(src/main.cc):只有 qt_ts->language() 与 gd_ts->language() 前两位语言码一致时才安装,避免界面主语言与 Qt 控件语言错配。
配置项 interfaceLanguage 的读写位置在 src/config.cc(加载)与 src/config.cc(保存),均为 preferences.xml 中的普通文本节点;设置界面语言后需要重启程序生效(界面文案"Restart the program to apply the language change"可在 locale/en.ts 中检索到对应源字符串)。
五、构建与打包:从 .ts 到 .qm 的流水线
命名规范还贯穿于构建系统。查看 CMakeLists.txt 的 "add translations" 段落:
# include all *ts files under locale
file(GLOB TRANS_FILES "locale/*.ts")
if (WIN32)
# Put generated files to output dir's locale
set_source_files_properties(${TRANS_FILES} PROPERTIES OUTPUT_LOCATION "${GD_WIN_OUTPUT_DIR}/locale")
else ()
set_source_files_properties(${TRANS_FILES} PROPERTIES OUTPUT_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/locale")
endif ()
qt_add_translations(${GOLDENDICT} TS_FILES ${TRANS_FILES}
QM_FILES_OUTPUT_VARIABLE qm_files
LUPDATE_OPTIONS "-no-ui-lines -locations none -no-obsolete")
add_dependencies(${GOLDENDICT} "release_translations")
要点有三:
file(GLOB TRANS_FILES "locale/*.ts")自动收集locale/下全部.ts文件,新增语言文件后无需改动 CMake 即被纳入构建——这也是对文件命名唯一性要求的侧面约束:文件名就是翻译的唯一标识;qt_add_translations在构建期调用lrelease类工具把.ts编译为.qm(翻译加载阶段实际读取的正是.qm),Windows 平台产物输出到安装目录的locale/子目录,其他平台输出到构建目录的locale/;- 生成的翻译目录与程序定位逻辑对接:
getLocDir()(src/config.cc)依次尝试程序数据目录下的locale子目录与应用目录下的locale,失败则回退到applicationDirPath() + "/locale",保证各平台都能找到编译产物。
六、贡献者实操清单:如何新增或维护一个语言文件
综合文档规范与源码机制,为 goldendict-ng 新增或调整界面翻译时应遵循以下决策流程:
- 判断是主方言还是次要变体:若该语言存在多个方言变体,先确认你维护的是否为主方言。主方言文件使用裸语言代码(如
es.ts、pt.ts、de.ts),让系统自动检测能覆盖同一语言的所有区域用户。 - 次要变体附加区域代码:与主方言差异较大、需要独立文案的变体,使用
语言_区域命名(如es_AR.ts、pt_BR.ts、de_CH.ts),与裸语言主文件共存于locale/目录。 - 不要轻易给裸语言文件改名:裸语言文件承担着"自动检测兜底命中"与"显式加载默认目标"的双重职责,将其改名为带区域后缀的文件(如
es_ES)会导致其他区域用户自动检测失配,破坏 locale/README.md 承诺的"auto-detection may just work"行为。 - 遵循 Qt Linguist 文件头约定:每个
.ts文件头的<TS version="2.1" language="..." sourcelanguage="en">中,language属性应与文件名语言代码保持一致(可对照 locale/en.ts 的结构)。 - 提交后验证构建:由于
file(GLOB TRANS_FILES "locale/*.ts")自动收集,新增文件会在下次 CMake 配置时自动纳入;确认.qm生成到getLocDir()所能找到的locale/路径下,并在目标系统区域中实测自动检测与显式选择两种加载路径。
总结
goldendict-ng 的本地化体系可以概括为一句话:文件名里的语言代码代表"语言本身",区域代码只属于需要单独维护的次要变体。仓库中 es.ts / es_AR.ts、pt.ts / pt_BR.ts、de.ts / de_CH.ts 的并存格局,正是 locale/README.md 规范的直接投影;而 src/main.cc 的双路径加载逻辑与 CMakeLists.txt 的自动收集机制,则为这套命名规范提供了运行时与构建期的双向支撑。理解并遵循这条规范,既能保证全球不同区域用户通过系统自动检测获得正确的界面语言,也能让维护者在多方言语言上做到主次分明、翻译资源不重叠。