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

📁 支持的翻译文件格式

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

1. YAML (.yml / .yaml)

特点：

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

示例 locales/en.yml：

en:
  common:
    save: &save Save  # 定义锚点
    cancel: Cancel
  users:
    title: Users List
    save: *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");

use rust_i18n::t;

fn main() {
    // 设置全局语言
    rust_i18n::set_locale("en");

    println!("{}", t!("hello")); // 输出: Hello, World!
    println!("{}", t!("greet", name = "Rust")); // 输出: Hello, Rust!

    // 也可以在调用时临时指定语言
    println!("{}", t!("hello", locale = "zh-CN")); // 假设有中文翻译，则会输出对应中文
}

🎯 如何选择？

• 个人项目/快速原型：推荐 YAML，书写最快，无需引号
• 团队协作/大型项目：推荐 TOML，注释明确，结构清晰
• 前后端分离/API集成：推荐 JSON，与其他系统交互最方便
• 需要翻译复用：只能选择 YAML，因为它支持锚点

无论选择哪种格式，rust-i18n 都提供一致的 API 和工具链支持，你可以随时切换格式而无需修改代码逻辑。

如果你正在寻找一种无额外依赖、能够将翻译直接嵌入二进制，并且希望有配套工具链来简化翻译管理的 Rust 国际化方案，rust-i18n 是一个值得考虑的选项。