# 国际化 (i10n) 使用指南
## 概述
Mint Runtime 内置了基于静态字符串的轻量级国际化支持，所有日志和输出都可以通过翻译键进行多语言适配。
## 核心特性
- ✅ 基于 `&'static str` 的零开销抽象
- ✅ 线程安全的全球化实例 (`OnceLock`)
- ✅ 支持中英文双语
- ✅ 便捷的日志宏支持
- ✅ 易于扩展的翻译系统
## 使用方法
### 1. 初始化国际化系统
在程序启动时调用 `init_i18n()`：
```rust
fn main() {
// 初始化国际化系统（默认语言：中文）
i10n::init_i18n();
// 其他初始化代码...
}
```
### 2. 使用翻译函数
#### 基础用法
```rust
// 获取翻译文本
let text = i10n::t("runtime_init");
println!("{}", text); // 输出：运行时初始化
```
#### 在日志中使用
```rust
// 普通日志
log::info!("{}: {}", i10n::t("security_check"), "检查完成");
// 使用国际化宏（推荐）
info_i18n!("task_complete");
error_i18n!("lua_error", "：{}", error_message);
warn_i18n!("permission_denied", "：{}", resource_name);
```
### 3. 添加新的翻译
编辑 `src/i10n.rs` 文件，在 `init_i18n()` 函数中添加新的翻译条目：
```rust
pub fn init_i18n() {
let mut i18n = I18n::new();
i18n.set_language("zh");
// 添加新的翻译
i18n.add_translation("your_key", "zh", "中文翻译");
i18n.add_translation("your_key", "en", "English translation");
// ... 其他翻译
I18N_INSTANCE.set(i18n).expect("Failed to initialize i18n");
}
```
## 支持的翻译键
当前已注册的翻译键：
| `runtime_init` | 运行时初始化 | Runtime initialized |
| `security_check` | 安全检查 | Security check |
| `lua_error` | Lua 错误 | Lua error |
| `config_load` | 配置加载 | Configuration loaded |
| `task_complete` | 任务完成 | Task completed |
| `permission_denied` | 权限拒绝 | Permission denied |
| `bytecode_verify` | 字节码验证 | Bytecode verification |
| `env_modify_blocked` | 环境修改被阻止 | Environment modification blocked |
| `external_call_hook` | 外部调用钩子 | External call hook |
| `log_rate_limit` | 日志速率限制 | Log rate limit |
| `promise_resolved` | Promise 已解析 | Promise resolved |
| `promise_rejected` | Promise 已拒绝 | Promise rejected |
| `module_loaded` | 模块已加载 | Module loaded |
## 切换语言
目前语言在初始化时固定为中文（"zh"）。如需支持动态切换，可以扩展 `set_lang()` 函数。
## 宏说明
### `info_i18n!`
信息级别日志宏：
```rust
// 简单用法
info_i18n!("config_load");
// 带参数
info_i18n!("module_loaded", "：{}", module_name);
```
### `error_i18n!`
错误级别日志宏：
```rust
error_i18n!("lua_error", "：{}", error_details);
```
### `warn_i18n!`
警告级别日志宏：
```rust
warn_i18n!("permission_denied", "：{}", resource);
```
### `log_i18n!`
通用日志宏，支持指定日志级别：
```rust
use log::Level;
log_i18n!(Level::Info, "task_complete");
```
## 示例代码
完整示例：
```rust
use mintrt::i10n;
fn main() {
// 初始化国际化
i10n::init_i18n();
// 初始化日志系统
env_logger::init();
// 使用国际化日志
info_i18n!("runtime_init");
// 模拟一个操作
let config_name = "config.ron";
info_i18n!("config_load", "：{}", config_name);
// 安全检查
log::info!("{}: 完成", i10n::t("security_check"));
// 任务完成
info_i18n!("task_complete");
}
```
## 输出示例
### 中文输出
```
[INFO] 运行时初始化
[INFO] 配置加载：config.ron
[INFO] 安全检查：完成
[INFO] 任务完成
```
### 英文输出（未来支持切换语言后）
```
[INFO] Runtime initialized
[INFO] Configuration loaded: config.ron
[INFO] Security check: completed
[INFO] Task completed
```
## 设计原理
### 为什么使用 `&'static str`？
1. **零堆分配**：所有翻译字符串都是静态字符串，编译期确定，无需运行时分配内存
2. **高性能**：直接返回字符串引用，无拷贝开销
3. **线程安全**：静态生命周期保证多线程访问安全
4. **内存效率**：所有线程共享同一份字符串数据
### `OnceLock` 的作用
`OnceLock` 确保全球化实例只初始化一次，后续访问都是零成本读取，完美契合国际化系统的需求。
## 扩展建议
如需添加更多语言支持：
1. 在 `init_i18n()` 中添加对应语言的翻译
2. 扩展 `set_language()` 方法支持动态切换
3. 考虑从外部文件加载翻译（如 JSON/YAML 格式）
## 注意事项
⚠️ **重要提示**：
- 翻译键必须是 `'static str` 类型
- 翻译文本也必须是 `'static str` 类型
- 如果找不到翻译，会返回键本身作为默认值
- 国际化系统必须在首次使用前初始化