> 🌐 Language: [English](i18n) | **中文**

# i18n(多语言)

支持四种 UI 语言,**实时切换**(切语言不用重启)。

## 支持

| Code | 名称 |
|---|---|
| `en` | English |
| `zh-CN` | 简体中文(默认) |
| `zh-TW` | 繁體中文 |
| `ja` | 日本語 |

## 切换

主窗口 **⚙** → 界面 → 语言下拉。改了 → `saveSettings({ lang })` → 全 app 重渲染。

## 实现机制

### String table

`src/shared/i18n.ts` —— 四语言的扁平 key → string map:

```ts
const STRINGS = {
  'sidebar.newSession': { en: 'New', 'zh-CN': '新建', 'zh-TW': '新建', ja: '新規' },
  'head.cwdPh': { en: 'Working directory', 'zh-CN': '工作目录', ... },
  // ...
};
```

每个 key 一个对象,四个语言字段。

### `t(lang, key, params?)`

```ts
export function t(lang: Lang, key: string, params?: Record<string, string | number>): string;
```

- 查 STRINGS[key][lang],没找到回退到 en,再没找到回退到 key 本身
- params 替换占位符:`t('zh-CN', 'al.httpErr', { code: 500, detail: 'timeout' })` → `HTTP 500 错误 — timeout`
- 占位符语法:`{code}` `{detail}`

### 渲染层

UI 字符串两种绑定方式:

1. **JS 显式调**:`el.textContent = t(lang, 'sidebar.newSession')`
2. **HTML 声明式**(更常用):`<button data-i18n="sidebar.newSession">新建</button>`,然后 `applyI18nDOM` 扫 `[data-i18n]` / `[data-i18n-placeholder]` / `[data-i18n-title]` 批量填

`applyI18nDOM`(`src/renderer/files-pane.ts:53` 是一个例子)在切语言时统一重扫。

## 不翻译的部分

**给模型看的字符串不译**:

- baseSystemPrompt(永远是中文,即便 UI 是英文)
- engine error messages(中文,因为是模型 prompt 的一部分)
- AGENTS.md / CLAUDE.md / KINET.md / KINET-CONTEXT.md(用户写的)
- 长期记忆内容(模型抽的)
- 工具结果(`shell` 输出、文件内容等)

理由:这些是给 LLM 的 prompt 内容,翻成英文会让 GLM/Claude 等模型的中文任务表现变差(用户用中文下任务,system prompt 也得是中文才贴合)。

## 默认 zh-CN 的理由

GLM 智谱(默认 provider)是中文模型,主要用户群中文。baseSystemPrompt 也是中文。

## 加新语言

1. `src/shared/i18n.ts` 加 `'xx'` 到 `Lang` union
2. 每个 STRINGS 项加 `'xx'` 翻译
3. `src/renderer/index.html`(或对应 view)的语言下拉加 `<option value="xx">`
4. typecheck → ship

不加新 key 不需要改其他地方。

## 加新 key

1. `STRINGS` 加新 key + 四语言翻译
2. UI 用 `data-i18n="new.key"` 或 JS 调 `t(lang, 'new.key')`
3. ship

## 关键源文件

- `src/shared/i18n.ts` —— STRINGS + `t()`
- `src/shared/types.ts:46` —— `AppSettings.lang: Lang`
- `src/renderer/app.ts` —— 顶部 `applyI18nDOM()` + 切语言时重扫
- `src/renderer/files-pane.ts:53` —— files 窗口的 `applyI18nDOM`(独立窗口要自己调)