update-client/i18n/ReadMe.txt

客户端国际化说明
================

这份文档说明 Qt 国际化文件怎么维护，以及哪些步骤是自动的、哪些步骤需要你手动做。

先看结论
========

Visual Studio 和 PowerShell 二选一即可。

- Visual Studio 是图形界面入口。
- PowerShell 是命令行入口。
- 两者最终调用的是同一套 CMake 目标，不是两套流程。

最重要的规则：

1. 普通“全部重新生成”会自动把已有的 update-client_zh_CN.ts 编译成 update-client_zh_CN.qm。
2. 普通“全部重新生成”不会自动扫描源码生成新的 update-client_zh_CN.ts 条目。
3. 如果新增了 QObject::tr(...)、QCoreApplication::translate(...) 这类新文案，必须先手动生成一次 update_client_lupdate。
4. 你编辑完 update-client_zh_CN.ts 后，再“全部重新生成”，CMake 会自动生成 .qm，并通过 qrc 打进程序。

文件说明
========

1. update-client_zh_CN.ts
   翻译源文件，XML 格式。新增或修改代码里的 tr()/translate() 文案后，需要更新这个文件，再补中文翻译。

2. update-client_zh_CN.qm
   Qt 运行时加载的二进制翻译文件。它由 .ts 编译生成，不要手工编辑。

3. update-client.qrc
   Qt 资源文件。它会把 update-client_zh_CN.qm 编进 Launcher、Updater、Bootstrap、MainApp，不需要把 .qm 单独放到安装目录。

日常编译：没有新增界面文字
==========================

这种情况最简单。

你只是改了普通 C++ 代码，或者只是修改了 update-client_zh_CN.ts 里已有条目的中文翻译：

Visual Studio：

```text
选择 x64 Release 或 x64 Debug -> 全部重新生成
```

PowerShell 等价命令：

```powershell
cd C:\Users\admin\Desktop\update-client
cmake --build --preset x64-release
```

这时 CMake 会自动执行 lrelease：

```text
update-client_zh_CN.ts -> update-client_zh_CN.qm
```

然后 .qm 会通过 update-client.qrc 打进 exe。

新增界面文字后的完整流程
========================

如果代码里新增了这些文字：

```cpp
QObject::tr("New message")
QCoreApplication::translate("Context", "New message")
```

只点“全部重新生成”是不够的。因为“全部重新生成”不会自动扫描源码，把新 source 写进 .ts。

正确流程是：

1. 先更新 .ts 文件。

   Visual Studio：

   ```text
   在 CMake 目标里找到 update_client_lupdate，然后生成这个目标。
   ```

   PowerShell 等价命令：

   ```powershell
   cd C:\Users\admin\Desktop\update-client
   cmake --build --preset x64-release --target update_client_lupdate
   ```

   这一步会扫描 Common、Bootstrap、Launcher、Updater、MainApp 里的 cpp/h 文件，把新增的 tr()/translate() 文案写入：

   ```text
   i18n/update-client_zh_CN.ts
   ```

2. 编辑 update-client_zh_CN.ts。

   找到新增的 `<source>...</source>`，把对应 `<translation>...</translation>` 补成中文。

   可以用 Qt Linguist 打开，也可以直接用文本编辑器编辑 XML。

3. 再重新生成程序。

   Visual Studio：

   ```text
   全部重新生成
   ```

   PowerShell 等价命令：

   ```powershell
   cmake --build --preset x64-release
   ```

   这一步会自动做：

   ```text
   update-client_zh_CN.ts -> update-client_zh_CN.qm -> update-client.qrc -> exe
   ```

如果只想单独生成 .qm
====================

一般不需要单独做。普通编译会自动生成 .qm。

如果你只是想检查 .ts 能不能正常编译成 .qm，可以单独生成这个目标：

Visual Studio：

```text
生成 CMake 目标 update_client_translations
```

PowerShell：

```powershell
cd C:\Users\admin\Desktop\update-client
cmake --build --preset x64-release --target update_client_translations
```

常见问题
========

1. 新增了 tr()，为什么程序里没有中文？

   通常是少做了 update_client_lupdate。新增文案后必须先更新 .ts，再补中文，再重新生成。

2. 我只改了 .ts 里的中文，还要跑 update_client_lupdate 吗？

   不需要。直接“全部重新生成”即可，CMake 会自动重新生成 .qm。

3. update-client_zh_CN.qm 要不要交付到安装目录？

   不需要。它已经通过 update-client.qrc 编进 exe。

4. 代码里能不能直接写中文？

   不建议。界面文字统一写英文 source，然后在 .ts 里翻译成中文。

5. Visual Studio 或 CMake 找不到 lupdate / lrelease 怎么办？

   通常是 Qt 环境变量没配好。确认 CMAKE_PREFIX_PATH 或 Qt5_DIR 指向 Qt 目录。

   Windows 示例：

   ```powershell
   [Environment]::SetEnvironmentVariable("CMAKE_PREFIX_PATH", "C:\Qt\5.15.2\msvc2019_64", "User")
   ```

   Linux 示例：

   ```bash
   sudo apt install -y qttools5-dev-tools
   ```