当前位置：首页 > news >正文

【rust-i18n】简介

news 2026/5/11 22:27:08

rust-i18n是一个用于 Rust 的国际化（i18n）库，它的核心目标是让文本本地化变得简单和易用。它的 API 设计灵感来自 Ruby 的ruby-i18n和 Rails 框架的 I18n 模块。

📁 支持的翻译文件格式

rust-i18n支持三种主流的配置文件格式，你可以根据项目需求选择最适合的一种或混合使用：

1. YAML (.yml / .yaml)

特点：

最常用：作为默认推荐格式，文档示例最丰富
可读性强：使用缩进表示层级，结构清晰直观
支持锚点和别名：可以复用重复的翻译片段
无需引号：纯文本可以直接书写，无需额外标点

示例locales/en.yml：

en:common:save:&saveSave# 定义锚点cancel:Cancelusers:title:Users Listsave:*save# 引用锚点

2. JSON (.json)

特点：

生态兼容：与前端工具链和Web服务无缝对接
严格结构：强制使用花括号和引号，避免格式错误
工具支持：有大量的JSON编辑器和格式化工具
易于自动化：适合CI/CD流程自动处理

示例locales/en.json：

{"en":{"common":{"save":"Save","cancel":"Cancel"},"users":{"title":"Users List"}}}

3. TOML (.toml)

特点：

Rust原生：语法与Rust的类型系统风格一致
显式层级：使用点号和表头明确表示层级关系
类型明确：天然支持字符串、整数、布尔等类型
注释支持：可以用#添加注释，便于团队协作

示例locales/en.toml：

[en] title = "My App" # 应用标题 [en.common] save = "Save" cancel = "Cancel" [en.users] title = "Users List"

🔄 三种格式的特点对比

特性	YAML	JSON	TOML
可读性	⭐⭐⭐ 最佳，缩进清晰	⭐⭐ 一般，括号较多	⭐⭐⭐ 很好，结构明确
简洁度	⭐⭐⭐ 最简洁，无需引号	⭐ 较冗余，需要引号和逗号	⭐⭐ 中等，需要表头
注释支持	⭐⭐ 支持 (#)	❌ 不支持	⭐⭐⭐ 支持 (#)
复用能力	⭐⭐⭐ 支持锚点和别名	❌ 不支持复用	❌ 不支持复用
工具生态	⭐⭐ 较好	⭐⭐⭐ 最好	⭐⭐ 较好
Rust风格	⭐⭐ 一般	⭐⭐ 一般	⭐⭐⭐ 最匹配
编辑友好	⭐⭐ 缩进敏感	⭐⭐⭐ 自动格式化	⭐⭐⭐ 结构明确

🚀 核心理念与特点

编译时加载：翻译文件（如 YAML、JSON、TOML）在编译时就被加载并直接包含到二进制文件中。这意味着在程序运行时，翻译文本的获取速度极快，且不依赖外部文件。
简单的t!宏：提供了一个全局可用的t!宏，你可以在代码的任何地方通过一个键名来获取翻译后的字符串，使用起来非常直观。
灵活的翻译文件：支持两种组织翻译文件的方式，你可以根据项目需求选择：
1. 按语言拆分：每种语言一个独立的文件（如en.yml,zh-CN.yml），适合传统的翻译工作流。
2. 集中管理：将所有语言的翻译放在同一个文件中（如app.yml），利用 AI（如 GitHub Copilot）自动填充其他语言的翻译。
强大的辅助工具：提供了一个cargo i18n命令行工具，可以自动扫描你的 Rust 源码，提取出所有使用t!宏但尚未翻译的文本，并生成待翻译的文件，极大地简化了本地化流程。
丰富的现代特性：支持带参数的翻译（如Hello, %{name}）、多级语言回退机制（如zh-CN找不到时自动找zh）、可插拔的自定义后端，以及为超长文本生成短键以优化内存等功能。

💡 快速上手

在Cargo.toml中添加依赖：

[dependencies] rust-i18n = "3"

在项目根目录创建locales文件夹，并放入翻译文件，例如locales/en.yml：

en:hello:"Hello, World!"greet:"Hello, %{name}!"

在你的 Rust 代码中初始化和使用：

// 初始化，指定翻译文件路径rust_i18n::i18n!("locales");userust_i18n::t;fnmain(){// 设置全局语言rust_i18n::set_locale("en");println!("{}",t!("hello"));// 输出: Hello, World!println!("{}",t!("greet",name="Rust"));// 输出: Hello, Rust!// 也可以在调用时临时指定语言println!("{}",t!("hello",locale="zh-CN"));// 假设有中文翻译，则会输出对应中文}