类型安全本地化Spirula Studio如何把漏翻译变成编译错误【免费下载链接】spirula-studioCross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA.项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studioSpirula Studio 是一款跨平台的 3D Gaussian Splatting 训练器支持视频到 splat 再到 mesh运行在 Vulkan 或 CUDA 上其界面支持13 种语言。它的国际化方案有一个核心理念把翻译变成类型而不是查找键于是漏翻译这种常年潜伏的 bug直接变成了编译错误——构建不过代码就合不进去。为什么漏翻译是最难发现的 bug大多数项目的本地化方案是这样的消息用一个字符串 ID 做 key运行时去查一张表查不到就回退到英文。问题在于回退是静默的——界面上悄悄出现一句英文用户只会觉得这里没翻译而开发者一年都察觉不到翻译散落在 json 或 .po 文件里代码和翻译是两套世界编译器帮不上任何忙。Spirula Studio 的做法是把这件事翻过来翻译本身是 C 的类型系统的一部分缺失、重复、数量不对统统在编译期爆炸。一个文件定义全部语言语言的单一事实来源整套机制只依赖一张语言表写在 src/i18n/Languages.h#define SS_LANGUAGES(X) X(en, en, English, English) X(ja, ja, 日本語, Japanese) X(zh_hans, zh-Hans, 简体中文, Chinese (Simplified)) X(zh_hant, zh-Hant, 繁體中文, Chinese (Traditional)) X(ko, ko, 한국어, Korean) /* … 共 13 种语言 */这是 X-macro 模式Lang枚举、每条消息的槽位数、语言选择菜单、--lang参数解析器全部从这张表派生。注释里说得很直白在这里加一行所有还没有该语言翻译的消息都会让构建失败——这正是目的。一条消息就是一个类型SS_MSG 的魔法写一条消息长这样见 src/i18n/README.mdSS_MSG(start_training, EN(Start Training), JA(学習を開始), ZH_HANS(开始训练), /* … */);它展开成 src/i18n/Message.h 里一个constexpr的Msg对象每种语言一个槽位 一条static_assert检查所有槽位都填了。于是各种手滑都有对应的编译错误错误类型你会得到什么少了一种语言static_assertstart_training is missing a translation同一种语言写了两次同一条断言重复必然导致别的槽位空着标签数量不对专门的断言wrong number of translations语言表加了、但标签宏没加BeginCatalog.h里的金丝雀先报错并直接点名这个文件两个细节值得一提顺序无关每个语言标签自带槽位下标JA()写在EN()前面也没关系按读起来舒服的顺序写即可金丝雀机制src/i18n/BeginCatalog.h 底部放了一条只含x的完整 13 语言消息。如果你往SS_LANGUAGES加了新语言却忘了在这里加标签宏构建会在这个文件而不是在某条倒霉的消息上报错错误信息直接告诉你该去哪个文件补。还有个逃生舱SS_MSG_EN(name, …)让所有槽位先填英文保证功能可用同时可被grep出来清点——bash tools/check_i18n.sh会报告还剩多少条没翻。目前的答案是0全部消息都带齐了 13 种语言。第二道防线连没进消息表都逃不掉光有类型系统还不够。Msg看不见ImGui::Button(Start)这种写法——它编译完全正常只是永远不会被翻译。Spirula Studio 从另一侧堵上了这条路src/app/gui/Ui.h 里的所有 UI 封装只接受const Msg——传裸字符串直接编译不过tools/check_i18n.sh 作为 lint 挂在构建流程里只要src/app/gui/下有任何带文本的ImGui::调用绕过Ui.h构建失败。真正不需要翻译的文本路径、文件名、GPU 设备名、引擎日志走ui::*Raw重载——名字里带个Raw就是为了让这里故意不翻译在 diff 里一眼可见。两道防线合起来忘了翻译就没有入口了想偷懒的方式被谁拦下消息缺一种语言类型系统static_assert字符串压根没做成消息lintcheck_i18n.sh两条事后很难补的书写规则文档里特别强调了两条纪律见 docs/i18n.md① 永远不要拼接句子片段。日语、韩语、土耳其语都是动词在句尾的停止训练 对象 这种英文语序的拼装根本没法翻译。正确做法是整句写成一条消息用{0}/{1}占位符ui::Text(msg::dataset_summary, {cameras, views, points});② 不写对复数敏感的句式。写Objects: 3而不是3 objects——否则俄语需要三形式的 CLDR 复数规则所有带计数的消息都会膨胀三倍。目录里所有计数消息都刻意用标签式而非屈折式。有意思的细节翻译的子进程协议GUI 会拉起spirula mesh子进程并带上--lang于是子进程打印的是日语而 GUI 的进度条还得读懂它。去匹配英文片段的做法在工具被翻译的那一刻就会碎掉所以 src/i18n/Message.h 提供了format()的逆运算scan()给它同一条Msg和子进程打印的那行文字它把占位符里藏着的数字抽还给你。整条协议里一个英文字符都没有翻译怎么改都不会破坏父子进程之间的对话。字体层面同理内嵌的 CJK 子集字体是从翻译目录生成的翻译里出现新字符就可能让子集过期于是tools/check_font_coverage.py每次构建都跑一遍超界即失败。添加一种语言要几步得益于一切从Languages.h派生流程短得离谱在 src/i18n/Languages.h 的SS_LANGUAGES里加一行在 src/i18n/BeginCatalog.h 加标签宏、src/i18n/EndCatalog.h 加对应的#undef忘了也没关系金丝雀会点名提醒构建——所有缺译的消息会以各自的 C 名字列成一堆编译错误那份清单就是你的待办列表需要的话为新文字补充字体子集并运行python3 tools/make_ui_font.py重新生成。写在最后Spirula Studio 的本地化方案没有引入任何重型框架全部核心逻辑就在 src/i18n/ 这一小撮文件里但它把翻译完整性从运行时约定提升成了编译期事实。对任何做多语言的项目这套思路都值得偷师语言集合写成单一事实来源X-macro一切从它派生翻译即类型缺失 断言失败重复 断言失败数量错 断言失败用类型参数签名 lint 双保险堵住字符串根本没进消息表的后门为故意不翻译留一条可见的合法通道*Raw重载而不是让大家悄悄绕过体系。想继续深挖推荐两份文档src/i18n/README.md 讲机制本身docs/i18n.md 讲如何发布一个本地化构建含字体子集、SS_DEFAULT_LANG与SS_FONT_CJK构建选项。【免费下载链接】spirula-studioCross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA.项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考