# OpenClaw 国际化 (I18N) 文档

## 概述

OpenClaw 仪表板支持多语言国际化，当前已实现：

- **中文 (zh)** - 默认语言
- **英文 (en)** - 备选语言

## 已汉化文件清单

### 后端文件

| 文件路径 | 汉化内容 |
|---------|---------|
| `src/openclaw/dashboard/app.py` | API 响应消息、警报标题、WebSocket 消息类型 |
| `src/openclaw/dashboard/models.py` | 字段描述（docstrings） |

### 前端文件

| 文件路径 | 汉化内容 |
|---------|---------|
| `src/openclaw/dashboard/templates/index.html` | 页面标题、导航、指标标签、图表标题、表格列头、状态文本 |
| `src/openclaw/dashboard/templates/config.html` | 页面标题、导航、配置项标签、按钮文本、状态消息 |
| `src/openclaw/dashboard/static/config.js` | 加载/保存状态消息、控制台日志、成功/错误提示 |

### 国际化工具

| 文件路径 | 说明 |
|---------|------|
| `src/openclaw/dashboard/i18n.py` | 国际化支持类，提供双语翻译字典 |

## 使用国际化工具

### 基础用法

```python
from openclaw.dashboard.i18n import I18n, t

# 创建实例（默认中文）
i18n = I18n()

# 获取翻译
title = i18n.t("status.agent_bankrupt")  # "代理破产"

# 切换语言
i18n.set_language("en")
title = i18n.t("status.agent_bankrupt")  # "Agent Bankrupt"
```

### 字符串插值

```python
# 支持变量替换
msg = i18n.t("alert.bankruptcy_msg", agent_id="bull_001")
# 中文: "代理 bull_001 已破产！"
# 英文: "Agent bull_001 has gone bankrupt!"
```

### 使用全局快捷函数

```python
from openclaw.dashboard.i18n import t, set_language

# 使用默认实例
text = t("metrics.system_equity")  # "系统权益"

# 切换全局语言
set_language("en")
text = t("metrics.system_equity")  # "System Equity"
```

## 翻译键值参考

### 状态消息 (`status`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `status.agent_bankrupt` | 代理破产 | Agent Bankrupt |
| `status.large_loss_detected` | 检测到重大损失 | Large Loss Detected |
| `status.config_saved` | 配置已保存 | Configuration Saved |
| `status.loading_config` | 正在加载配置... | Loading Configuration... |
| `status.confirm` | 已确认 | Confirmed |
| `status.not_found` | 未找到 | Not Found |
| `status.realtime` | 实时 | Realtime |
| `status.disconnected` | 已断开 | Disconnected |

### 导航 (`nav`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `nav.dashboard` | 仪表盘 | Dashboard |
| `nav.config` | 配置 | Configuration |
| `nav.overview` | 总览 | Overview |

### 指标 (`metrics`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `metrics.system_equity` | 系统权益 | System Equity |
| `metrics.total_pnl` | 总盈亏 | Total P&L |
| `metrics.active_agents` | 活跃 Agent | Active Agents |
| `metrics.total_trades` | 总交易数 | Total Trades |
| `metrics.avg_win_rate` | 平均胜率 | Avg Win Rate |

### 代理状态 (`agent`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `agent.status` | 状态 | Status |
| `agent.balance` | 余额 | Balance |
| `agent.win_rate` | 胜率 | Win Rate |
| `agent.trades` | 交易数 | Trades |
| `agent.thriving` | 🚀 繁荣 | 🚀 Thriving |
| `agent.stable` | 💪 稳定 | 💪 Stable |
| `agent.struggling` | ⚠️ 困难 | ⚠️ Struggling |
| `agent.critical` | 🔴 危急 | 🔴 Critical |
| `agent.bankrupt` | 💀 破产 | 💀 Bankrupt |

### 交易 (`trade`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `trade.recent_trades` | 最近交易 | Recent Trades |
| `trade.time` | 时间 | Time |
| `trade.symbol` | 交易对 | Symbol |
| `trade.side` | 方向 | Side |
| `trade.buy` | 买入 | BUY |
| `trade.sell` | 卖出 | SELL |
| `trade.pnl` | 盈亏 | P&L |

### 警报 (`alert`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `alert.title` | 警报 | Alert |
| `alert.critical` | 严重 | Critical |
| `alert.error` | 错误 | Error |
| `alert.warning` | 警告 | Warning |
| `alert.info` | 信息 | Info |
| `alert.bankruptcy_title` | 代理破产 | Agent Bankrupt |
| `alert.bankruptcy_msg` | 代理 {agent_id} 已破产！ | Agent {agent_id} has gone bankrupt! |
| `alert.large_loss_title` | 检测到重大损失 | Large Loss Detected |
| `alert.large_loss_msg` | 代理 {agent_id} 遭受重大损失: ${pnl:.2f} | Agent {agent_id} suffered large loss: ${pnl:.2f} |

### 配置 (`config`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `config.title` | 配置管理 | Configuration Management |
| `config.save` | 保存配置 | Save Configuration |
| `config.reset` | 重置 | Reset |
| `config.saving` | 保存中... | Saving... |
| `config.initial_capital` | 初始资金 | Initial Capital |
| `config.cost_structure` | 成本结构 | Cost Structure |
| `config.thresholds` | 生存阈值 | Survival Thresholds |
| `config.simulation` | 模拟设置 | Simulation Settings |
| `config.llm_providers` | LLM 提供商 | LLM Providers |

### WebSocket 消息 (`ws`)

| 键值 | 中文 | 英文 |
|-----|------|------|
| `ws.status_update` | 状态更新 | Status Update |
| `ws.initial_state` | 初始状态 | Initial State |
| `ws.agent_update` | 代理更新 | Agent Update |
| `ws.trade_update` | 交易更新 | Trade Update |
| `ws.alert` | 警报 | Alert |

## 添加新语言

要添加新语言（如日语），请按以下步骤操作：

### 1. 更新 Language 枚举

```python
# 在 i18n.py 中的 Language 类添加
class Language(str, Enum):
    CHINESE = "zh"
    ENGLISH = "en"
    JAPANESE = "jp"  # 新增
```

### 2. 添加翻译字典

```python
# 在 _translations 字典中添加
"jp": {
    "status": {
        "agent_bankrupt": "エージェント破産",
        "config_saved": "設定を保存しました",
        # ... 更多翻译
    },
    # ... 其他分类
}
```

### 3. 更新 get_available_languages 方法

```python
def get_available_languages(self) -> Dict[str, str]:
    return {
        "zh": "中文",
        "en": "English",
        "jp": "日本語",  # 新增
    }
```

### 4. 添加语言切换功能（前端）

如需前端语言切换，可添加 API 端点：

```python
@app.post("/api/language/{lang}")
async def set_language_endpoint(lang: str) -> Dict[str, str]:
    """切换仪表板语言。"""
    try:
        i18n.set_language(lang)
        return {"status": "success", "message": f"Language set to {lang}"}
    except ValueError as e:
        return {"status": "error", "message": str(e)}
```

## 扩展现有翻译

添加新的翻译键值：

```python
from openclaw.dashboard.i18n import I18n

i18n = I18n()

# 添加中文翻译
i18n.add_translation("zh", "new.category.key", "新的值")

# 添加英文翻译
i18n.add_translation("en", "new.category.key", "New Value")

# 使用新键值
text = i18n.t("new.category.key")
```

## 最佳实践

1. **键名规范**
   - 使用小写字母和下划线
   - 采用 `分类.子分类.键名` 的层级结构
   - 例如：`status.agent_bankrupt`, `trade.recent_trades`

2. **变量插值**
   - 使用 `{variable}` 语法
   - 确保所有语言版本包含相同的变量名
   - 示例：`"agent {agent_id} 已破产"`, `"Agent {agent_id} has gone bankrupt"`

3. **语言回退**
   - 如果当前语言缺少翻译，自动回退到中文
   - 确保中文翻译完整作为基准

4. **前端集成**
   - 前端可直接通过 API 获取翻译
   - 考虑将语言偏好存储在本地存储或用户配置中

## 集成示例

### FastAPI 集成

```python
from fastapi import FastAPI
from openclaw.dashboard.i18n import I18n

app = FastAPI()
i18n = I18n()

@app.get("/api/translations")
async def get_translations(lang: str = "zh"):
    """获取指定语言的完整翻译字典。"""
    i18n.set_language(lang)
    return i18n.get_all_translations()

@app.get("/api/translate/{key}")
async def translate(key: str, lang: str = "zh"):
    """翻译单个键值。"""
    i18n.set_language(lang)
    return {"key": key, "translation": i18n.t(key)}
```

### WebSocket 消息汉化

```python
# app.py 中使用示例
from openclaw.dashboard.i18n import t

# 使用国际化消息
alert = AlertMessage(
    alert_type=AlertType.BANKRUPTCY,
    level=AlertLevel.CRITICAL,
    title=t("alert.bankruptcy_title"),
    message=t("alert.bankruptcy_msg", agent_id=agent.agent_id),
)
```

---

## 更新日志

### 2024-02-25
- ✅ 创建 i18n.py 国际化工具类
- ✅ 完成 index.html 汉化
- ✅ 完成 config.html 汉化
- ✅ 完成 config.js 汉化
- ✅ 完成 app.py API 消息汉化
- ✅ 创建本文档

### 待办事项
- [ ] 添加前端语言切换 UI
- [ ] 添加更多语言支持（日语、韩语等）
- [ ] 将翻译持久化到配置文件
- [ ] 支持用户个性化语言设置