docs: 优化国际化和客户端文档说明

i18n/ReadMe.txt

@@ -1,79 +1,176 @@
 客户端国际化说明
 ================
 
-本目录保存 Qt 国际化资源。
+这份文档说明 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
-   翻译源文件。新增或修改代码里的 tr() 文案后，需要更新这个文件，再补中文翻译。
+   翻译源文件，XML 格式。新增或修改代码里的 tr()/translate() 文案后，需要更新这个文件，再补中文翻译。
 
 2. update-client_zh_CN.qm
    Qt 运行时加载的二进制翻译文件。它由 .ts 编译生成，不要手工编辑。
 
 3. update-client.qrc
-   Qt 资源文件。它会把 update-client_zh_CN.qm 编进 Launcher / Updater / MainApp，不需要把 .qm 单独暴露到安装目录。
+   Qt 资源文件。它会把 update-client_zh_CN.qm 编进 Launcher、Updater、Bootstrap、MainApp，不需要把 .qm 单独放到安装目录。
 
+日常编译：没有新增界面文字
+==========================
 
-日常编译
+这种情况最简单。
-========
 
-普通重新生成项目时，CMake 会自动执行 lrelease，把 update-client_zh_CN.ts 编译成 update-client_zh_CN.qm。
+你只是改了普通 C++ 代码，或者只是修改了 update-client_zh_CN.ts 里已有条目的中文翻译：
 
-Visual Studio 里直接选择 x64 Release 或 x64 Debug，然后“全部重新生成”即可。
+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
+```
 
-如果代码里新增了 QObject::tr(...)、QCoreApplication::translate(...) 等需要翻译的文字，按下面步骤操作：
+然后 .qm 会通过 update-client.qrc 打进 exe。
 
-1. 更新 .ts 文件。
+新增界面文字后的完整流程
+========================
+
+如果代码里新增了这些文字：
+
+```cpp
+QObject::tr("New message")
+QCoreApplication::translate("Context", "New message")
+```
+
+只点“全部重新生成”是不够的。因为“全部重新生成”不会自动扫描源码，把新 source 写进 .ts。
+
+正确流程是：
+
+1. 先更新 .ts 文件。
 
    Visual Studio：
 
-   在 CMake 目标里生成 update_client_lupdate。
+   ```text
+   在 CMake 目标里找到 update_client_lupdate，然后生成这个目标。
+   ```
 
-   PowerShell：
+   PowerShell 等价命令：
 
    ```powershell
    cd C:\Users\admin\Desktop\update-client
    cmake --build --preset x64-release --target update_client_lupdate
    ```
 
-2. 打开 i18n/update-client_zh_CN.ts，补齐新增 source 对应的 translation。
+   这一步会扫描 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. 重新生成翻译和程序。
+3. 再重新生成程序。
 
    Visual Studio：
 
-   “全部重新生成”即可。
+   ```text
+   全部重新生成
+   ```
 
-   PowerShell：
+   PowerShell 等价命令：
 
    ```powershell
    cmake --build --preset x64-release
    ```
 
-   如果只想单独生成 .qm：
+   这一步会自动做：
 
-   ```powershell
+   ```text
-   cmake --build --preset x64-release --target update_client_translations
+   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. 代码里不要直接写中文界面文字，统一写英文 source，再在 .ts 里翻译成中文。
+1. 新增了 tr()，为什么程序里没有中文？
-2. .qm 已经通过 update-client.qrc 编进 exe，交付包里不需要单独放翻译文件。
+
-3. 如果 Visual Studio 或 CMake 找不到 lupdate / lrelease，通常是 Qt 环境变量没配好。确认 CMAKE_PREFIX_PATH 或 Qt5_DIR 指向 Qt 5.15.2 的 msvc2019_64 目录。
+   通常是少做了 update_client_lupdate。新增文案后必须先更新 .ts，再补中文，再重新生成。
-4. update_client_lupdate 只在新增或修改 tr() 文案后需要手动生成；普通代码修改只需要正常重新生成项目。
+
+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
+   ```