# OxideTerm 国际化 (i18n)

> 本文档描述 OxideTerm 的多语言支持架构、配置方法和扩展指南。

## 目录

1. [功能概述](#功能概述)
2. [支持的语言](#支持的语言)
3. [技术架构](#技术架构)
4. [目录结构](#目录结构)
5. [使用方法](#使用方法)
6. [添加新语言](#添加新语言)
7. [键值命名规范](#键值命名规范)

---

## 功能概述

OxideTerm 内置多语言支持，提供以下特性：

| 功能 | 说明 |
|------|------|
| 静态打包 | 翻译资源在构建时打包，无运行时 HTTP 请求 |
| 无闪烁切换 | 语言切换即时生效，无页面闪烁 |
| 自动检测 | 首次启动自动检测浏览器语言 |
| 持久化存储 | 语言偏好保存在本地存储 |
| 模块化翻译 | 按功能模块拆分翻译文件，便于维护 |

---

## 支持的语言

| 语言代码 | 语言名称 | 状态 |
|----------|----------|------|
| `zh-CN` | 简体中文 | ✓ 完整 |
| `zh-TW` | 繁體中文 | ✓ 完整 |
| `en` | English | ✓ 完整 |
| `de` | Deutsch | ✓ 完整 |
| `es-ES` | Español (España) | ✓ 完整 |
| `fr-FR` | Français (France) | ✓ 完整 |
| `it` | Italiano | ✓ 完整 |
| `ja` | 日本語 | ✓ 完整 |
| `ko` | 한국어 | ✓ 完整 |
| `pt-BR` | Português (Brasil) | ✓ 完整 |
| `vi` | Tiếng Việt | ✓ 完整 |

---

## 技术架构

### 技术栈

| 组件 | 说明 |
|------|------|
| i18next | 核心国际化库 |
| react-i18next | React 绑定 |
| 静态导入 | 构建时打包 JSON 资源 |
| localStorage | 持久化语言偏好 (`app_lang`) |

### 语言优先级

1. 本地存储 (`localStorage`)
2. 浏览器语言 (`navigator.language`)
3. 默认语言 (`zh-CN`)

---

## 目录结构

```
src/
├── i18n.ts                     # i18next 初始化配置
└── locales/
    ├── zh-CN/                  # 简体中文
    │   ├── ai.json
    │   ├── common.json
    │   ├── connections.json
    │   ├── editor.json
    │   ├── fileManager.json
    │   ├── forwards.json
    │   ├── ide.json
    │   ├── modals.json
    │   ├── plugin.json
    │   ├── profiler.json
    │   ├── sessionManager.json
    │   ├── sessions.json
    │   ├── settings.json
    │   ├── settings_view.json
    │   ├── sftp.json
    │   ├── sidebar.json
    │   ├── terminal.json
    │   └── topology.json
    ├── zh-TW/                  # 繁體中文
    ├── de/                     # Deutsch
    ├── en/                     # English
    ├── es-ES/                  # Español
    ├── fr-FR/                  # Français
    ├── it/                     # Italiano
    ├── ja/                     # 日本語
    ├── ko/                     # 한국어
    ├── pt-BR/                  # Português
    └── vi/                     # Tiếng Việt
```

### 翻译文件说明

| 文件 | 内容 |
|------|------|
| common.json | 通用文本：确认对话框、操作按钮、布局、标签页 |
| sidebar.json | 侧边栏：面板标题、操作按钮、工具提示 |
| settings.json | 设置面板基础文本 |
| settings_view.json | 设置视图：完整设置界面文本 |
| connections.json | 连接管理：状态、事件、连接池监控、重连 toast |
| forwards.json | 端口转发：快捷转发、表格、表单 |
| modals.json | 弹窗对话框：新建连接、导入导出、2FA 等 |
| sessions.json | 会话管理：面包屑、状态、操作 |
| sftp.json | SFTP 文件管理：文件列表、预览、传输队列 |
| terminal.json | 终端：本地终端、搜索、AI 助手、SSH 消息 |
| topology.json | 拓扑图：连接矩阵、错误边界 |
| ai.json | AI 功能：侧边栏聊天、内联助手、模型选择、提示词 |
| editor.json | 编辑器：IDE 模式内的代码编辑器文本 |
| ide.json | IDE 模式：文件树、项目管理、Git 状态 |
| plugin.json | 插件系统：插件列表、安装、配置、远程仓库 |
| profiler.json | 资源监控：CPU、内存、网络流量统计 |
| fileManager.json | 文件管理器：本地文件操作、路径选择 |

---

## 使用方法

### 在 React 组件中使用

```tsx
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('sidebar.panels.sessions')}</h1>
      <button>{t('common.actions.cancel')}</button>
    </div>
  );
}
```

### 在纯 TypeScript 中使用

```typescript
import i18n from '../i18n';

// 在函数内部调用（延迟翻译）
function showError() {
  const message = i18n.t('connections.state.error', { error: 'timeout' });
  toast.error(message);
}
```

### 带参数的翻译

```typescript
// JSON: "delete_batch": "确定删除 {{count}} 个连接？"
t('common.confirm.delete_batch', { count: 5 })
// 输出: "确定删除 5 个连接？"
```

### 切换语言

```typescript
import { useSettingsStore } from '../store/settingsStore';

const { setLanguage } = useSettingsStore();
setLanguage('en');  // 切换到英文
```

---

## 添加新语言

### 步骤 1：创建翻译文件

在 `src/locales/` 下创建新语言目录，复制英文翻译文件并翻译：

```bash
cp -r src/locales/en src/locales/ar  # 示例：添加阿拉伯语
```

### 步骤 2：更新 i18n.ts

1. 添加导入语句：

```typescript
// ar 翻译文件
import arCommon from './locales/ar/common.json';
import arSidebar from './locales/ar/sidebar.json';
// ... 其他文件
```

2. 合并翻译资源：

```typescript
const ar = {
  ...arCommon,
  ...arSidebar,
  // ... 其他文件
};
```

3. 注册到 i18next：

```typescript
resources: {
  // ... 其他语言
  'ar': { translation: ar }
}
```

4. 更新浏览器语言检测：

```typescript
if (browser.startsWith('ar')) return 'ar';
```

### 步骤 3：更新 settingsStore.ts

更新 Language 类型：

```typescript
export type Language = 'zh-CN' | 'en' | ... | 'ar';
```

### 步骤 4：更新 SettingsView.tsx

在语言选择器中添加新选项：

```tsx
<SelectItem value="ar">العربية</SelectItem>
```

---

## 键值命名规范

### 命名原则

| 规则 | 说明 |
|------|------|
| 语义化嵌套 | 按功能模块组织：`sidebar.panels.sessions` |
| 一致性前缀 | 同模块使用相同前缀 |
| 动作命名 | 按钮/操作使用动词：`actions.connect` |
| 状态命名 | 状态描述使用形容词：`status.connecting` |

### 命名空间示例

```json
{
  "sidebar": {
    "panels": {
      "sessions": "活动会话",
      "saved": "已保存连接"
    },
    "actions": {
      "expand": "展开侧边栏",
      "collapse": "收起侧边栏"
    }
  }
}
```

### 模块前缀

| 模块 | 前缀 | 示例 |
|------|------|------|
| SSH 连接 | `ssh.*` | `ssh.errors.auth_failed` |
| SFTP 文件 | `sftp.*` | `sftp.actions.download` |
| 端口转发 | `forwards.*` | `forwards.errors.port_in_use` |
| 通用操作 | `common.*` | `common.actions.cancel` |

---

## 注意事项

### 延迟翻译

在纯 TypeScript 文件中，避免在模块顶层调用 `i18n.t()`：

```typescript
// ❌ 错误：模块加载时 i18n 可能未初始化
const ERROR_MSG = i18n.t('errors.timeout');

// ✓ 正确：在函数内部调用
function getErrorMsg() {
  return i18n.t('errors.timeout');
}
```

### React 组件规范

- 使用 `useTranslation()` Hook
- 所有用户可见文本都需要翻译
- 包括 `title`、`placeholder`、`aria-label` 等属性

### 调试日志

调试日志保持英文，不翻译：

```typescript
// ✓ 调试日志
console.error('[SSH] Connection failed:', error);

// ✓ 用户可见消息需要翻译
toast.error(i18n.t('ssh.errors.connection_failed'));
```
