itools-localization 0.0.0

Internationalization support for iTools
Documentation

itools-i18n

国际化支持模块 for iTools，提供完整的国际化功能，包括翻译管理、语言切换和参数化翻译。

特性

  • ✅ 支持多语言翻译
  • ✅ 参数化翻译
  • ✅ 复数形式支持
  • ✅ 性别形式支持
  • ✅ 语言自动检测和切换
  • ✅ 翻译缓存机制
  • ✅ 错误处理和回退机制
  • ✅ 支持 Fluent 格式

快速开始

基本使用

use itools_i18n::{t, t_with_args};

// 基本翻译
let hello = t("messages.hello");

// 带参数的翻译
let greeting = t_with_args("messages.greeting", &[("name", "John")]);

语言切换

use itools_i18n::{set_locale, get_locale};

// 设置语言
set_locale("zh-CN");

// 获取当前语言
let current_locale = get_locale();

高级用法

自定义翻译提供者

use itools_i18n::{SimpleTranslator, I18nContext};

// 创建简单翻译提供者
let mut translator = SimpleTranslator::new("en", "en");

// 添加翻译
let mut en_translations = std::collections::HashMap::new();
en_translations.insert("messages.hello".to_string(), "Hello world!".to_string());
translator.add_translations("en", en_translations);

// 创建国际化上下文
let mut context = I18nContext::new(Box::new(translator));

// 使用翻译
let hello = context.t("messages.hello");

使用 Fluent 格式

use itools_i18n::{FluentTranslator, I18nContext};
use std::path::Path;

// 创建 Fluent 翻译提供者
let mut translator = FluentTranslator::new("en", "en");

// 从文件加载翻译
let path = Path::new("locales/en.ftl");
translator.add_translations_from_file("en", path).unwrap();

// 从字符串加载翻译
let ftl_content = r#"
messages.hello = Hello world!
messages.greeting = Hello, {name}!
"#;
translator.add_translations_from_string("en", ftl_content).unwrap();

// 创建国际化上下文
let mut context = I18nContext::new(Box::new(translator));

// 使用翻译
let hello = context.t("messages.hello");
let greeting = context.t_with_args("messages.greeting", &[("name", "John")]);

配置

环境变量

  • LANG: 设置默认语言
  • ITOOLS_LOCALE_EN: 英文翻译文件路径
  • ITOOLS_LOCALE_ZH_CN: 中文翻译文件路径
  • ITOOLS_LOCALE_{LANG}: 其他语言翻译文件路径

翻译文件格式

使用 Fluent (.ftl) 格式：

# 基本翻译
messages.hello = Hello world!

# 带参数的翻译
messages.greeting = Hello, {name}!

# 复数形式
messages.item_count = { $count ->
    [one] There is { $count } item
    *[other] There are { $count } items
}

# 性别形式
messages.greeting = { $gender ->
    [male] Hello, Mr. { $name }!
    [female] Hello, Ms. { $name }!
    *[other] Hello, { $name }!
}

性能优化

  • 翻译缓存: 使用 LRU 缓存存储翻译结果，减少重复翻译
  • 资源预加载: 启动时预加载常用语言的翻译资源
  • 懒加载: 仅在需要时加载翻译资源
  • 错误处理: 优雅处理翻译错误，回退到默认语言或键本身

与 Oak 系列库的集成

虽然 oak-fluent 库尚未实现，但 itools-i18n 模块设计为与 Oak 系列库保持一致的架构风格：

  • 模块化设计: 采用与 Oak 系列库相同的模块化架构
  • 一致性接口: 提供统一的翻译接口
  • 可扩展性: 支持自定义翻译提供者
  • 性能优化: 采用与 Oak 系列库相同的性能优化策略

示例

基本示例

use itools_i18n::{t, t_with_args, set_locale};

fn main() {
    // 设置语言
    set_locale("en");
    
    // 基本翻译
    println!("{}", t("messages.hello"));
    
    // 带参数的翻译
    println!("{}", t_with_args("messages.greeting", &[("name", "John")]));
    
    // 切换到中文
    set_locale("zh-CN");
    
    // 中文翻译
    println!("{}", t("messages.hello"));
    println!("{}", t_with_args("messages.greeting", &[("name", "张三")]));
}

复数形式示例

use itools_i18n::{t_with_args};

fn main() {
    // 测试复数形式
    for count in 0..5 {
        println!("{}", t_with_args("messages.item_count", &[("count", &count.to_string())]));
    }
}

故障排除

翻译不显示

  • 检查翻译文件是否存在且格式正确
  • 检查翻译键是否正确
  • 检查语言设置是否正确

参数不替换

  • 确保参数名称与 Fluent 文件中的一致
  • 确保参数值类型正确

语言切换不生效

  • 检查 LANG 环境变量设置
  • 检查翻译文件路径是否正确
  • 检查语言代码是否符合标准（如 "en", "zh-CN"）

贡献

欢迎贡献代码、报告问题或提出建议！

许可证

MIT