OpenLogi 国际化架构解析23 种语言 YAML 文件与 Crowdin 翻译流水线【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogiOpenLogi 是一个用 Rust 编写的本地优先的罗技外设配置工具Logi Options 的开源替代方案它没有账号、没有遥测通过 HID 协议实现按键重映射、DPI 与 SmartShift 调节。而它的界面国际化i18n做得同样扎实仅凭23 个语言 YAML 文件加一条Crowdin 自动翻译流水线就让设置界面覆盖从英语到简体中文的 22 种语言。本文带你拆解这套架构的设计思路。一、23 个 YAML 文件一个目录搞定全部语言所有界面文案集中存放在 crates/openlogi-ui/locales/ 目录每个语言一个文件| 语言文件 | 语言 | 语言文件 | 语言 | | -- | -- | -- | -- | | en.yml | 英语源语言 | el.yml | 希腊语 | | de.yml | 德语 | ru.yml | 俄语 | | fr.yml | 法语 | uk.yml | 乌克兰语 | | es.yml | 西班牙语 | ja.yml | 日语 | | it.yml | 意大利语 | zh-CN.yml | 简体中文 | | nl.yml | 荷兰语 | zh-HK.yml | 繁體中文香港 | | pt-PT.yml / pt-BR.yml | 葡萄牙语葡/巴西 | zh-TW.yml | 正體中文臺灣 | | da.yml / sv.yml / nb.yml | 丹/瑞/挪 | ko.yml | 韩语 | | pl.yml / fi.yml / tr.yml | 波/芬/土 | | |打开任意文件就能看到它极简单的格式——英文原文就是键key译文是值例如 en.ymlNo devices connected: No devices connectedQuit OpenLogi: Quit OpenLogiDPI presets: DPI presets这种「键 英文原文」的 gettext 风格设计带来两个好处漏翻译零成本兜底——运行时找不到对应键直接回退显示英文界面不会崩坏Crowdin 平台天然理解——翻译者看到的待译内容就是最终产品里的英文文案。二、编译期内嵌 运行时切换rust_i18n 的用法译文不是运行时从磁盘读的而是在编译期打进二进制。桌面端入口 main.rs 用一行宏完成全部目录的加载rust_i18n::i18n!(../openlogi-ui/locales, fallback en);之后代码里所有调用点直接用英文字符串取词例如tr!(Bind %{name}, name x)还支持%{count} devices这类参数插值。语言协商系统 locale 如何映射到文件真正决定「用户的系统语言 → 用哪个 yml」的逻辑在共享库 locale.rs它定义了SUPPORTED语言表22 项与文件名一一对应并处理了三类容易踩坑的 BCP-47 场景中文四路分流zh-Hans一律简体中文文字系统优先zh-Hant-HK归香港地区优先裸zh-Hant归台湾葡萄牙语按地区拆分pt-BR与pt-PT两套目录挪威语合并nb/nn/no全部折叠到nb书面挪威语。解析优先级为用户显式设置 系统 locale 英文未知代码比如klingon不会报错而是安全地回退。这套实现被设置应用和浮层两个进程共用避免两边对语言的理解打架。用户侧的入口在设置页的语言选择器 language.rs第一项「跟随系统」加上 22 个原生语言名选项切换即时生效、无需重启。三、质量护栏两条测试防止语言目录「漂移」多语言项目最常见的事故是功能迭代改了英文文案但只更新了部分语言文件。OpenLogi 用两条测试锁死这一点键完整性测试locale.rs 的locale_files_have_the_same_keys以 en.yml 为基准逐键比对全部 22 个语言目录缺键或多键都会让 CI 失败端到端取词测试i18n.rs真正加载目录验证Settings → 设置、DPI → 灵敏度等关键条目连「拼错一个键会静默回退英文」这种隐蔽问题都能抓到。官方规则也因此明确新增文案必须同一次提交落到所有 yml 文件非英文值可以先填英文占位后续由 Crowdin 补真实译文。四、Crowdin 流水线快照 → 上传 → 下载 → 合并 → 开 PR非英文译文的日常维护不在 git 里手动改而是交给 Crowdin。整条流水线由工作流 .github/workflows/crowdin.yml 驱动每晚定时运行并在 master 分支改动英文源文件时触发。映射关系由 .config/crowdin.yml 声明en.yml是上传源各语言走locales/%locale%.yml模板no→nb、sv-SE→sv这类差异用languages_mapping对齐。每次运行固定走 6 步DEVELOPMENT.md 有完整说明快照当前 git 里所有locales/*.yml到临时目录上传en.yml 作为源字符串上传各语言已有译文作为种子关掉import_eq_suggestions防止「值 英文」被误存为已完成译文下载Crowdin 导出开启skip_untranslated_strings未翻译字符串会被省略合并导出到快照中仅当工作区确实有真实翻译变化时才推送crowdin/i18n分支并开 PR。为什么必须「先快照再合并」直接下载 Crowdin 导出有两个已踩过的坑| 问题 | 后果 | | -- | -- | | 未翻译字符串以英文原文导回 | 英文「假译文」覆盖真实目录 | | 跳过未翻译项导致稀疏文件| 导出只含已翻译键直接覆盖会删掉其余全部键 |合并脚本 merge_crowdin_download.py 专门解决它们只接受值不同于英文源的译文、Crowdin 省略的键从快照恢复、文件头与_version行原样保留。脚本自带--self-test工作流每次运行前先自测。最终 PR 还要通过完整的 CI 检查——包括前面提到的键完整性测试——才会被合入。五、对新手开发者的三个借鉴单一源语言 键即原文新人加文案时心路最直——改英文、全量补占位、CI 把关不需要记任何 key 命名规则编译期嵌入目录i18n 零运行时 I/O缺失键自动回退英文翻译永远是渐进增强的翻译自动化要「幂等且保守」宁可多一步快照合并也不让机器导出直接覆盖人工资产——这是 Crowdin/Transifex 类平台接入的通用经验。完整文档见 docs/DEVELOPMENT.md本地配置好凭证后也可手动执行devenv tasks run openlogi:i18n-upload与i18n-download体验上传、下载全流程。【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenLogi 国际化架构解析：23 种语言 YAML 文件与 Crowdin 翻译流水线
OpenLogi 国际化架构解析23 种语言 YAML 文件与 Crowdin 翻译流水线【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogiOpenLogi 是一个用 Rust 编写的本地优先的罗技外设配置工具Logi Options 的开源替代方案它没有账号、没有遥测通过 HID 协议实现按键重映射、DPI 与 SmartShift 调节。而它的界面国际化i18n做得同样扎实仅凭23 个语言 YAML 文件加一条Crowdin 自动翻译流水线就让设置界面覆盖从英语到简体中文的 22 种语言。本文带你拆解这套架构的设计思路。一、23 个 YAML 文件一个目录搞定全部语言所有界面文案集中存放在 crates/openlogi-ui/locales/ 目录每个语言一个文件| 语言文件 | 语言 | 语言文件 | 语言 | | -- | -- | -- | -- | | en.yml | 英语源语言 | el.yml | 希腊语 | | de.yml | 德语 | ru.yml | 俄语 | | fr.yml | 法语 | uk.yml | 乌克兰语 | | es.yml | 西班牙语 | ja.yml | 日语 | | it.yml | 意大利语 | zh-CN.yml | 简体中文 | | nl.yml | 荷兰语 | zh-HK.yml | 繁體中文香港 | | pt-PT.yml / pt-BR.yml | 葡萄牙语葡/巴西 | zh-TW.yml | 正體中文臺灣 | | da.yml / sv.yml / nb.yml | 丹/瑞/挪 | ko.yml | 韩语 | | pl.yml / fi.yml / tr.yml | 波/芬/土 | | |打开任意文件就能看到它极简单的格式——英文原文就是键key译文是值例如 en.ymlNo devices connected: No devices connectedQuit OpenLogi: Quit OpenLogiDPI presets: DPI presets这种「键 英文原文」的 gettext 风格设计带来两个好处漏翻译零成本兜底——运行时找不到对应键直接回退显示英文界面不会崩坏Crowdin 平台天然理解——翻译者看到的待译内容就是最终产品里的英文文案。二、编译期内嵌 运行时切换rust_i18n 的用法译文不是运行时从磁盘读的而是在编译期打进二进制。桌面端入口 main.rs 用一行宏完成全部目录的加载rust_i18n::i18n!(../openlogi-ui/locales, fallback en);之后代码里所有调用点直接用英文字符串取词例如tr!(Bind %{name}, name x)还支持%{count} devices这类参数插值。语言协商系统 locale 如何映射到文件真正决定「用户的系统语言 → 用哪个 yml」的逻辑在共享库 locale.rs它定义了SUPPORTED语言表22 项与文件名一一对应并处理了三类容易踩坑的 BCP-47 场景中文四路分流zh-Hans一律简体中文文字系统优先zh-Hant-HK归香港地区优先裸zh-Hant归台湾葡萄牙语按地区拆分pt-BR与pt-PT两套目录挪威语合并nb/nn/no全部折叠到nb书面挪威语。解析优先级为用户显式设置 系统 locale 英文未知代码比如klingon不会报错而是安全地回退。这套实现被设置应用和浮层两个进程共用避免两边对语言的理解打架。用户侧的入口在设置页的语言选择器 language.rs第一项「跟随系统」加上 22 个原生语言名选项切换即时生效、无需重启。三、质量护栏两条测试防止语言目录「漂移」多语言项目最常见的事故是功能迭代改了英文文案但只更新了部分语言文件。OpenLogi 用两条测试锁死这一点键完整性测试locale.rs 的locale_files_have_the_same_keys以 en.yml 为基准逐键比对全部 22 个语言目录缺键或多键都会让 CI 失败端到端取词测试i18n.rs真正加载目录验证Settings → 设置、DPI → 灵敏度等关键条目连「拼错一个键会静默回退英文」这种隐蔽问题都能抓到。官方规则也因此明确新增文案必须同一次提交落到所有 yml 文件非英文值可以先填英文占位后续由 Crowdin 补真实译文。四、Crowdin 流水线快照 → 上传 → 下载 → 合并 → 开 PR非英文译文的日常维护不在 git 里手动改而是交给 Crowdin。整条流水线由工作流 .github/workflows/crowdin.yml 驱动每晚定时运行并在 master 分支改动英文源文件时触发。映射关系由 .config/crowdin.yml 声明en.yml是上传源各语言走locales/%locale%.yml模板no→nb、sv-SE→sv这类差异用languages_mapping对齐。每次运行固定走 6 步DEVELOPMENT.md 有完整说明快照当前 git 里所有locales/*.yml到临时目录上传en.yml 作为源字符串上传各语言已有译文作为种子关掉import_eq_suggestions防止「值 英文」被误存为已完成译文下载Crowdin 导出开启skip_untranslated_strings未翻译字符串会被省略合并导出到快照中仅当工作区确实有真实翻译变化时才推送crowdin/i18n分支并开 PR。为什么必须「先快照再合并」直接下载 Crowdin 导出有两个已踩过的坑| 问题 | 后果 | | -- | -- | | 未翻译字符串以英文原文导回 | 英文「假译文」覆盖真实目录 | | 跳过未翻译项导致稀疏文件| 导出只含已翻译键直接覆盖会删掉其余全部键 |合并脚本 merge_crowdin_download.py 专门解决它们只接受值不同于英文源的译文、Crowdin 省略的键从快照恢复、文件头与_version行原样保留。脚本自带--self-test工作流每次运行前先自测。最终 PR 还要通过完整的 CI 检查——包括前面提到的键完整性测试——才会被合入。五、对新手开发者的三个借鉴单一源语言 键即原文新人加文案时心路最直——改英文、全量补占位、CI 把关不需要记任何 key 命名规则编译期嵌入目录i18n 零运行时 I/O缺失键自动回退英文翻译永远是渐进增强的翻译自动化要「幂等且保守」宁可多一步快照合并也不让机器导出直接覆盖人工资产——这是 Crowdin/Transifex 类平台接入的通用经验。完整文档见 docs/DEVELOPMENT.md本地配置好凭证后也可手动执行devenv tasks run openlogi:i18n-upload与i18n-download体验上传、下载全流程。【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考