goldendict-ng 本地化指南:locale 目录翻译文件命名与语言区域代码规范

原创2026-10-04 09:23:131,996 阅读
文章标签:桌面应用

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(不要将区域代码与语言混为一谈)。

这句话的含义可以从两个层面理解:

  1. 命名语义层面:.ts 文件名的"主字段"应当表达语言本身(language),而非某个政治/地理区域(region/country)。例如语言代码 es 代表"西班牙语"这一语言,而不是"西班牙这个国家"。把它命名为 es_ES 虽然也能工作,但语义上把"语言"与"国家"绑定死了——事实上全球有超过 20 个国家以西班牙语为官方语言。
  2. 加载匹配层面: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")

要点有三:

  1. file(GLOB TRANS_FILES "locale/*.ts") 自动收集 locale/ 下全部 .ts 文件,新增语言文件后无需改动 CMake 即被纳入构建——这也是对文件命名唯一性要求的侧面约束:文件名就是翻译的唯一标识;
  2. qt_add_translations 在构建期调用 lrelease 类工具把 .ts 编译为 .qm(翻译加载阶段实际读取的正是 .qm),Windows 平台产物输出到安装目录的 locale/ 子目录,其他平台输出到构建目录的 locale/;
  3. 生成的翻译目录与程序定位逻辑对接:getLocDir()(src/config.cc)依次尝试程序数据目录下的 locale 子目录与应用目录下的 locale,失败则回退到 applicationDirPath() + "/locale",保证各平台都能找到编译产物。

六、贡献者实操清单:如何新增或维护一个语言文件

综合文档规范与源码机制,为 goldendict-ng 新增或调整界面翻译时应遵循以下决策流程:

  1. 判断是主方言还是次要变体:若该语言存在多个方言变体,先确认你维护的是否为主方言。主方言文件使用裸语言代码(如 es.ts、pt.ts、de.ts),让系统自动检测能覆盖同一语言的所有区域用户。
  2. 次要变体附加区域代码:与主方言差异较大、需要独立文案的变体,使用 语言_区域 命名(如 es_AR.ts、pt_BR.ts、de_CH.ts),与裸语言主文件共存于 locale/ 目录。
  3. 不要轻易给裸语言文件改名:裸语言文件承担着"自动检测兜底命中"与"显式加载默认目标"的双重职责,将其改名为带区域后缀的文件(如 es_ES)会导致其他区域用户自动检测失配,破坏 locale/README.md 承诺的"auto-detection may just work"行为。
  4. 遵循 Qt Linguist 文件头约定:每个 .ts 文件头的 <TS version="2.1" language="..." sourcelanguage="en"> 中,language 属性应与文件名语言代码保持一致(可对照 locale/en.ts 的结构)。
  5. 提交后验证构建:由于 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 的自动收集机制,则为这套命名规范提供了运行时与构建期的双向支撑。理解并遵循这条规范,既能保证全球不同区域用户通过系统自动检测获得正确的界面语言,也能让维护者在多方言语言上做到主次分明、翻译资源不重叠。

登录后查看全文
goldendict-ng