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

桌面应用【免费下载链接】goldendict-ngThe Next Generation GoldenDict项目地址https://gitcode.com/gh_mirrors/go/goldendict-ng点击查看免费下载导读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 的.tsTranslation 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 Spanishes_AR.ts阿根廷西班牙语es_BO.ts玻利维亚西班牙语pt.ts欧洲葡萄牙语European Portuguesept_BR.ts巴西葡萄牙语de.ts标准德语Standard Germande_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.ccIf interfaceLanguage is explicitly set, uses filename-based loading, because GD have more languages than Qt its locale database. If not, then let Qts 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 dirs 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翻译加载阶段实际读取的正是.qmWindows 平台产物输出到安装目录的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 version2.1 language... sourcelanguageen中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 的自动收集机制则为这套命名规范提供了运行时与构建期的双向支撑。理解并遵循这条规范既能保证全球不同区域用户通过系统自动检测获得正确的界面语言也能让维护者在多方言语言上做到主次分明、翻译资源不重叠。赞分享桌面应用【免费下载链接】goldendict-ngThe Next Generation GoldenDict项目地址https://gitcode.com/gh_mirrors/go/goldendict-ng点击查看免费下载相关推荐Laravel Lang 本地化代码Locale对照指南128 个语言目录与翻译规则的完整映射Laravel Lang 本地化代码Locale对照指南128 个语言目录与翻译规则的完整映射 本指南以 Laravel Lang 仓库中的本地化规则文档后端Kilo 仓库多语言翻译术语表Locale Glossary机制详解从命名规范到翻译工作流落地Kilo 仓库多语言翻译术语表Locale Glossary机制详解从命名规范到翻译工作流落地 导读 本文讲解 Kilo 开源仓库中用于管理多语言翻译术语人工智能大模型AI Agent代码智能体工具调用交互助手CLIFluxer 荷兰语本地化指南nl locale 翻译规范与 i18n 工程实践Fluxer 荷兰语本地化指南nl locale 翻译规范与 i18n 工程实践 Fluxer 是一款免费开源、面向好友、群组与社区的即时通讯与 VoIP 聊上一篇一条命令解开PKGRePKG的TEX转PNG纹理提取下一篇老游戏在新 Windows 上双击闪退5 分钟用 DDrawCompat 恢复 DirectDraw 兼容创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考