# CrossDesk 界面本地化

桌面端和 Android、iOS、HarmonyOS 移动端共用 `catalog.json` 中的界面文案，支持以下 10 种语言版本：

| 语言 | 标识 |
| --- | --- |
| 简体中文 | `zh-Hans` |
| English | `en` |
| Русский | `ru` |
| 繁體中文 | `zh-Hant` |
| 日本語 | `ja` |
| 한국어 | `ko` |
| Deutsch | `de` |
| Français | `fr` |
| Español | `es` |
| Português (Brasil) | `pt-BR` |

## 语言选择

- 新安装的桌面端默认“跟随系统”，也可以在设置中手动指定语言。已有配置中的中文、英文、俄文选择继续保留。
- 移动端使用系统语言；Android 和 iOS 同时支持操作系统提供的应用语言设置。
- 地区变体匹配相应语言；中文优先识别 `Hans` / `Hant`，台湾、香港、澳门使用繁体。葡萄牙语地区变体共用巴西葡萄牙语文案。
- 支持系统首选语言列表的平台使用其中可用的语言，没有匹配项时回退到英文。修改系统语言后重新打开应用可确保所有页面与状态文案更新。
- 只翻译应用界面。远端设备名称、文件名、用户输入、服务器公告和协议内容不作翻译。隐私政策正文使用项目已发布的中文或英文版本，第三方许可证保留原文。

## 维护资源

`catalog.json` 是唯一编辑入口，生成结果提交到各平台目录，应用运行时不依赖翻译服务。

```sh
python3 localization/generate.py
python3 localization/generate.py --check
```

生成器使用 Python 标准库，输出桌面 C++ 文案表、Android 原生资源及语言声明、iOS `.lproj` 资源，以及 HarmonyOS 文案表。`--check` 检查语言覆盖、格式占位符和生成文件是否同步。

新增文案时，在 `strings` 中提供所有语言的译文，并加入 `platforms` 中对应的平台列表。桌面命名键同时加入 `desktop`；Slint 使用的键追加到 `slint` 列表末尾，已有索引不能重排。桌面语言顺序中的前 3 项与历史配置兼容，修改顺序需要配置迁移。

占位符须完整保留：Android/HarmonyOS 使用 `{0}` 等位置占位符；iOS 使用 `%1$@` 等位置格式；已有桌面文案使用其原有格式。不同语言可以调整占位符位置，但不能更改数量或类型。新语言的初始译文包含机器辅助翻译，发布前应由对应语言使用者复核术语、语气及长文本。