前段时间给一个内部工具加多语言支持把 Rust 生态里的 i18n 方案翻了个遍最后锁定的是 rust-i18n。它的 README 不算长但信息密度很高读一遍觉得都懂了真上手才发现有不少值得展开的细节。这篇文章就以 rust-i18n 的 readme 为线索结合我实际跑通 Demo 和接入 axum 项目的经验把关键用法、配置项和容易踩的坑一次说清楚。适合刚接触 Rust 国际化、正在选型或者已经用上但想搞明白t!宏背后行为的人。1. rust-i18n 到底解决什么问题1.1 选型背景Rust 生态里 i18n 方案对比Rust 的国际化方案其实不少老牌的 gettext 绑定、Mozilla 团队做的 Project Fluent、还有偏桌面资源管理的 i18n-embed。我最早用的是 gettext 的绑定PO 文件那一套在 Linux 生态里很正统可一旦要把文案和前端同步维护编辑体验确实谈不上友好。后来翻到 rust-i18n 的 README第一印象很关键它没有把问题复杂化核心就两件事——用 YAML 写文案用宏取文案。README 里强调的三个特点——Lightweight、Easy to use、Support YAML——基本就是大家选它的原因。和 Fluent 那套复杂的术语体系比起来rust-i18n 的学习成本几乎可以忽略和 i18n-embed 那种偏资源管理的方案比它又更贴近 Web 服务常见的“请求级语言识别”场景。如果你是在做一个需要快速上手中英双语的 Web 服务rust-i18n 是综合成本最低的选项之一。1.2 设计取向编译期代码生成与两个宏的心智模型rust-i18n 属于“编译期代码生成”路线。i18n!宏在编译阶段读取你指定的 locale 文件把 YAML 里的文案结构直接生成进二进制运行时不再做文件解析也没有动态查表逻辑。这个取向和 Fluent 那种运行时解析器完全相反换来的是极低的调用开销特别适合对延迟敏感的服务端程序。用一句话概括它的工作模型把所有翻译文案按语言放在 YAML 文件里代码里声明一次加载目录之后所有取翻译的地方都用t!宏完成。整个过程只涉及两个宏——rust_i18n::i18n!(locales)负责加载t!(hello)负责取文案。这种心智模型非常轻团队新成员看 README 半小时就能上手。这里有个值得展开的点i18n!宏生成的不是一份运行时字典而是一组针对每个文案 key 的静态访问代码。所以你的 key 写错时很多错误在编译期就能暴露比运行时才发现某个语言包漏了翻译要舒服得多。当然并不是所有 key 都能在编译期校验到位这个后面讲坑的时候再细说。2. 按 README 把第一个 Demo 完整跑起来2.1 依赖和目录结构先用 cargo 添加依赖cargo add rust-i18n然后在项目根目录创建locales文件夹locales/ ├── en.yml └── zh-CN.ymlREADME 默认约定的加载路径就是locales目录你也可以在i18n!宏里传别的路径但用默认结构最省心。目录名就叫locales别拼成locale或者lang这种错误排查起来非常浪费时间。2.2 YAML 语言文件的写作约定以最经典的 hello world 为例# locales/en.yml en: hello: Hello world messages: hello: Hello, %{name}# locales/zh-CN.yml zh-CN: hello: 你好世界 messages: hello: 你好%{name}这里有两个必须注意的约定。第一YAML 顶层必须有一个语言标签这个标签会作为语言标识名字要和你后续要切换的 locale 完全一致。第二实际使用中我建议所有文案值都加引号避免 YAML 解析器把冒号、百分号这类特殊符号当成语法结构处理。2.3 i18n! 与 t! 的最小调用链use rust_i18n::t; rust_i18n::i18n!(locales); fn main() { println!({}, t!(hello)); }i18n!宏放在 crate 根的某个位置调用一次后整个项目都能用t!取翻译。运行后默认会走当前系统语言如果你的系统是中文环境输出就是“你好世界”。如果想强制看英文效果可以在运行时加环境变量控制这个下文会专门讲。2.4 改文件不生效编译期宏的构建直觉这里有一个 README 不会特意强调、但新手一定会遇到的点i18n!是编译期宏修改 YAML 文件之后必须重新触发编译运行时改动文件是不会生效的。大多数时候cargo run会自动检测但如果你遇到“改了文案但输出没变”的诡异情况先别怀疑缓存停掉进程重新 build 一次。我建议在项目文档里写明“修改 locales 后需要重新构建”团队协作时能省掉不少沟通成本。另一个经验是YAML 文件结构改动较大时偶尔会遇到宏生成的缓存没刷新此时cargo clean后重新构建基本都能解决代价是编译时间长一点但比自己怀疑人生强。3. t! 宏的进阶玩法插值、复数、层级访问3.1 插值参数文案里的动态部分多语言文案几乎不可能没有变量rust-i18n 的插值语法用的是 Ruby i18n 同款的%{name}占位符en: messages: hello: Hello, %{name}t!(messages.hello, name world) // Hello, world这个设计很直白占位符和参数名一一对应。实际项目里我习惯在 YAML 文件顶部用注释写下当前文件里所有用到的参数名不然文案一多很容易出现拼写不一致。插值参数最终会做字符串替换如果你的场景需要传入数字或者其它类型传参时先转成字符串即可。3.2 复数规则不只 one 和 other复数大概是 i18n 里最容易翻车的地方。rust-i18n 沿用了 gettext 的思路用one和other两个特殊 keyen: messages: count: one: %{count} message other: %{count} messagest!(messages.count, count 1) // 1 message t!(messages.count, count 2) // 2 messages判断依据是count参数是否等于 1。对英文这种“单复数二态”的语言够用但对中文这种没有复数变化的语言我通常两个 key 写一样的值就好。需要提醒的是如果复数文案里没有用到%{count}调用时传了 count 虽然不会报错但翻译结果里没有数字用户看到会困惑最好保持占位符和参数名一致。3.3 点号嵌套和数组下标文案多了之后全平铺在一个层级会很难维护。rust-i18n 支持用点号访问嵌套 keyen: common: buttons: confirm: Confirm cancel: Cancelt!(common.buttons.confirm)嵌套层级没有硬性限制但建议不要超过三四层否则 YAML 缩进写起来痛苦点号字符串也容易看花眼。另外 README 里提到它还能通过数字下标访问数组里的文案en: mails: - title: Hello %{name}t!(mails.0.title, name world)这个能力在做邮件模板、富文本分段这类场景非常实用尤其是当文案结构本身是列表时不需要为了取一个字段而单独拆一个 key。3.4 手动指定语言与动态 key 的边界t!宏支持locale参数相当于一次调用的临时语言覆盖t!(hello, locale zh-CN) // 你好世界这个参数在测试里尤其好用你可以不依赖环境变量直接断言某个 key 在指定语言下的输出。在 Web 场景里它也能绕开中间件带来的语言感知强制让某条短信、邮件走固定语言。要注意的是t!的 key 通常需要是字符串字面量而不是运行时变量因为宏生成的是静态访问代码。如果非要在运行时动态拼 key会失去编译期校验的能力我一般会尽量避免这种写法实在需要就自己维护一层映射表把有限的动态 key 枚举出来。4. Web 框架集成从查询参数到自动识别4.1 按框架开启对应 featurerust-i18n 为常见 Web 框架提供了官方集成README 里列了 axum、actix-web、rocket、warp 四类。启用方式是在 Cargo.toml 里加 feature[dependencies] rust-i18n { version 3, features [axum] }对应的 feature 名称如下框架featureaxumaxumactix-webactix-webrocketrocketwarpwarp不需要 Web 集成时默认不开这些 feature依赖树会干净很多。我用的是 axum下面的示例就以它为例。4.2 axum 示例与中间件识别来源README 里的 axum 示例大致是这样一个结构use axum::{Router, routing::get}; use rust_i18n::t; rust_i18n::i18n!(locales); async fn hello() - String { t!(hello).to_string() } #[tokio::main] async fn main() { let app Router::new() .route(/, get(hello)) .layer(rust_i18n::axum::I18nLayer::new()); // 监听 3000 端口 }加上I18nLayer之后中间件会从请求里识别语言t!宏就能感知当前请求的语言。识别来源包括查询参数、Cookie、Header 等一般来说查询参数优先级较高便于前端做“当前页面手动切换语言”的功能。实际调试时我习惯用 curl 直接验证curl http://localhost:3000/?localezh-CN一条命令就能确认中间件是否生效。不过不同版本的中间件在细节上可能有差异比如查询参数叫什么名字、Cookie 的 key 是什么接入时一定以自己锁定的版本 README 为准。我遇到过升级小版本导致行为变化的情况所以 Web 集成功能不要盲目升级。4.3 手动语言切换与线程局部状态如果你没开任何 Web feature或者请求来源比较特殊接口里也能手动设置语言。rust-i18n 允许在当前线程里设置 locale具体宏是rust_i18n::set_locale!设置之后当前线程后续的t!调用都会优先用它。这里涉及一个很重要的底层行为locale 状态是线程粒度的不是全局的。在异步多线程 runtime 下不同任务可能运行在不同线程你在线程 A 设置了语言线程 B 的t!不一定能感知到。所以在写 Web 服务时我建议要么靠框架中间件统一设置要么在真正需要固定语言的场景直接传locale参数而不是依赖 set_locale 的隐式状态。这个坑后面还会专门展开。5. 环境变量与构建期配置几个开关分别怎么用5.1 默认语言与 CI 稳定性默认情况下如果系统语言和可用语言对不上rust-i18n 会回退到某个默认语言。README 里提供了一个环境变量来控制这个默认值RUST_I18N_YAMLen cargo run这个变量在构建期决定“当无法从请求或系统识别语言时用哪个语言的文案兜底”。它对 CI 很重要CI 环境通常语言环境不统一你不希望测试断言被系统 locale 影响。我的做法是在 CI 脚本里显式加上RUST_I18N_YAMLen保证测试环境语言永远一致这样断言就不会因为跑在不同机器上而随机失败。5.2 自动加载与文件格式选择rust-i18n 还支持自动加载方式启用后构建时会自动扫描locales目录下的所有语言文件省去手动在宏里声明文件列表的样板代码。不过自动加载也意味着你无法在代码里显式控制加载顺序如果不同文件之间有依赖关系手动声明反而更可控。我的建议小项目无所谓大项目优先手动声明明确列出每个语言文件。如果你想在代码里拿到当前编译进二进制的语言列表rust-i18n 还提供了available_locales!宏。我在做语言选择器接口时用过它直接返回可用语言数组前端拿到就能渲染非常方便。除了默认的 YAMLrust-i18n 还支持 JSON、TOML、RON 三种格式通过 feature 开启格式featureYAML默认JSONjsonTOMLtomlRONron选格式主要看团队习惯和工具链。如果文案需要和前端共享JSON 更容易被前端工具链读取如果完全给 Rust 服务用YAML 的注释能力是很大的加分项我最终选了 YAML。5.3 minimal 模式与依赖瘦身README 里有个minimalfeature启用后会压缩依赖体积。它适合对二进制体积或编译时间敏感的场景。这个模式会移除一些非必要的宏辅助代码功能上基本不受影响。如果你的项目本身依赖已经很多建议直接开 minimal能明显感觉到编译时间改善。这里需要提醒一下开启 minimal 模式前确认你的应用没有用到那些被裁剪的非核心特性。我一般是在项目稳定之后再做这个优化开发期先保持默认配置避免排查问题时多一个变量。6. 实战项目中积累的踩坑经验6.1 异步 runtime 下的语言状态丢失前面提到了rust-i18n 的当前语言状态是线程局部的。在 axum 这种基于 Tokio 的多线程 runtime 里如果你在某个异步任务里调用了set_locale!转头在另一个任务里查文案极有可能拿到默认语言。我踩过一次非常隐蔽的 bug一个后台任务在生成邮件时设置了英文另一个任务生成 PDF 时却拿到了中文。排查到最后发现就是线程切换导致的。这个问题的规避方法很朴素能传locale参数就传参数不要在异步代码里依赖隐式的全局状态。如果你确实需要“请求级别的语言”走框架中间件让它在每个请求入口统一设置然后这个请求的任务链上全程带上显式参数。6.2 key 缺失时的回退行为与 CI 校验当t!里的 key 在当前语言文件中不存在时rust-i18n 的行为是回退到默认语言如果默认语言里也没有就会原样返回 key 字符串。这个行为在开发期能帮你快速发现漏翻译但在生产环境里用户会直接看到一串英文点号路径观感很差。我的做法是写一个简单的检查脚本在 CI 里对所有语言文件做 key 一致性校验确保每个语言的 key 集合完全一致。脚本逻辑不复杂遍历所有 YAML 文件收集每个文件下的完整 key 路径然后比对集合是否相等。这样根本不会把漏翻译留到线上。别把希望寄托在运行时回退上那不是设计用来兜底的只是避免崩溃的保险丝。6.3 locale 命名别混用rust-i18n 对语言标签的处理比较宽容但为了少踩坑请统一使用zh-CN、en-US这种带连字符的风格不要混合zh_CN和下划线风格。一个项目里同时出现两种风格迟早会出“设置了zh_CN但文件里只有zh-CN”这种低级问题。如果历史原因已经混了在 CI 里加一条规则强制统一。6.4 版本升级与团队规范沉淀rust-i18n 还在快速迭代期我在一次从 2.x 升 3.x 时就遇到过 feature 名称和中间件 API 变化。升级前先看 changelog尤其是t!宏的参数行为、中间件的默认解析逻辑。另外锁好版本Cargo.lock 不要随便动除非这次升级是团队明确要做的。最后分享一个我在真实项目里的组织习惯不管项目多大我都会维护一个locales/README.md里面记清楚“新增文案的步骤”“key 命名规范”“哪个环境变量控制什么”相当于把 i18n 约定沉淀成团队文档。这个文件的模板就是从 rust-i18n 主 README 里提炼出来的。代码会迭代规范文档往往是团队里活得最久的东西。
