# 插件多语言（i18n）指南

插件界面支持多种语言：shell 自带 **简体中文（zh）** 和 **English（en）**，插件还通过
`ctx.locale.addLanguage()` 注册了 **繁體中文（zh-Hant）**、**日本語（ja）**、**한국어（ko）**、
**Français（fr）**、**Deutsch（de）**、**Español（es）**、**Русский（ru）**。
用户可以在 DSH 的「设置 → 通用 → 语言」里切换，切换后插件界面（设置页、双语面板）立即生效。

## 目录结构

```
src/client/locales/
├── index.ts        # 语言注册表、fallback、格式化工具（一般不用改）
├── zh.json         # 权威 key 清单（简体中文，必须齐全）
├── en.json         # 英文（必须与 zh 的 key 完全一致）
├── zh-Hant.json    # 繁体中文（可只翻一部分，缺的回退 zh → en）
├── ja.json / ko.json / fr.json / de.json / es.json / ru.json
```

## 翻译规则

1. **只改 JSON**，不要改 `index.ts` 或其它 TS 文件（基础设施由维护者改）。
2. key 必须与 `zh.json` 完全一致，不允许自造 key（拼错会在测试里报错）。
3. 文案里的 `{name}` 是插值位，翻译时保留原名（如 `{version}`、`{used}`、`{ms}`），
   可以调整它们在句子里的位置。
4. 只翻正文，不要翻译 key、模型名称（Hy-MT2、Q4_K_M 等）和许可证名（Apache-2.0、MIT）。
5. 简体/繁体优先按当地习惯用词（如「设置/設定」「端口/連接埠」）。

## 查看翻译进度

```powershell
npm run i18n:status
```

输出每种语言的完成度、缺哪些 key、有没有未知 key。`en` 必须 100% 且无未知 key，
其它语言可以逐步补齐（缺的回退 `en`）。

## 新增一种语言

1. 在 `src/client/locales/` 新建 `<id>.json`（`id` 是 BCP 47 风格，如 `it`、`pt-BR`）。
2. 在 `src/client/locales/index.ts` 的 `LOCALES` 里导入并登记；
3. 在 `LOCALE_PACKS` 里加一行 `{ id: 'it', label: 'Italiano', fallback: 'en' }`
   （繁体这类同语族语言可以 `fallback: 'zh'`，fallback 链最终必须到 en）；
4. 跑 `npm run i18n:status` 和 `npm test`。

## 实现要点

- **host 只给 key**：模型说明（`noteKey`）、provider 名称（`labelKey`）、自测错误
  （`errorCode`）都由 host 返回 key/枚举，客户端按当前语言渲染，host 不拼中文。
- **切换语言即时生效**：客户端订阅 `locale/change`（拿不到时退回观察 `<html lang>`），
  设置页强制重渲染，双语面板整体重建（表头/「翻译中…」等文案跟着换）。
- **数字/容量格式化**：用 `Intl.NumberFormat(当前语言)`，千分位、小数位随语言变化。
- **缺 key 回退**：shell 沿 fallback 链找（如 zh-Hant → zh → en），都没有才显示 key；
  组件里的兜底函数 `fallbackTranslate()` 先查 zh 再查 en。