CodePlanet 界面国际化维护说明

本文说明中英文界面切换的实现方式、日常维护步骤与常见问题。源语言为简体中文，英文通过 Qt 官方 QTranslator + .ts/.qm 提供。

架构概览

用户：工具 → 语言 → 中文 / English
        ↓
Application::setLocale("zh_CN" | "en")
        ↓
  zh_CN：removeTranslator
  en   ：load codeplanet_en.qm → installTranslator
        ↓
notifyLanguageChange() → 各控件 changeEvent(LanguageChange) → retranslateUi()

组件	职责
`Application`	安装/卸载翻译器、广播 `LanguageChange`、持久化 `ui/locale`
`resources/translations/codeplanet_en.ts`	翻译源（lupdate 生成/更新）
`resources/translations/codeplanet_en.qm`	运行时英文包（lrelease 编译）
`bin/translations/codeplanet_en.qm`	发布副本（构建或 `generate_i18n.bat` 复制）
各 GUI 控件	`tr("中文")` + `retranslateUi()`

路径	说明
`src/services/UiLocaleService.{h,cpp}`	`setLocale`、`applyStoredLocale`、`applySessionLocale`（子进程）
`src/editor/Application.{h,cpp}`	Ops `setLocale`、`applyStoredLocale`
`src/runtime/RuntimeMainWindow.cpp`	Runtime 界面 `tr()` + `retranslateUi()`；由 Launcher 传入 `--locale=en` 时英文生效（如「Mock 硬件触发 camA」→ `codeplanet_en.ts`）
`src/launcher/LauncherService.cpp`	启动 Runtime 时附加 `--locale=`
`src/editor/MainWindow.cpp`	主界面创建后调用 `applyStoredLocale()`
`src/gui/widgets/codeeditorwidget2.cpp`	语言菜单、`retranslateUi()`
`src/gui/widgets/*`	查找替换、参数、图片等子控件
`src/gui/editor/codeeditor.{h,cpp}`	行列状态栏文案
`scripts/generate_i18n.bat`	`lrelease` 并复制到 `bin/translations/`
`scripts/update_i18n_ts.bat`	`lupdate` 从源码刷新 `.ts`
`src/editor/editor.pro`	存在 `.qm` 时构建后复制到 `bin/translations/`

日常维护流程

1. 新增或修改界面文案

1. 在代码中使用 tr("中文源文")，类需带 Q_OBJECT。 2. 固定不翻译的标签（如语言名「中文」）使用：

   QString::fromUtf8(u8"中文");

不要用 QStringLiteral("中文")（MSVC 下可能乱码）。 3. 在控件中实现：

void retranslateUi();
changeEvent() 中处理 QEvent::LanguageChange 并调用 retranslateUi()。

4. 构造函数末尾调用一次 retranslateUi()。

2. 更新翻译表

REM 1. 从源码提取新字符串到 .ts
scripts\update_i18n_ts.bat

REM 2. 用 Qt Linguist 编辑 resources\translations\codeplanet_en.ts 中的英文

REM 3. 编译 .qm 并复制到 bin
scripts\generate_i18n.bat

generate_i18n.bat 内 Qt 路径默认为 D:\Qt\Qt5.11.1\5.11.1\msvc2017_64\bin，若本机不同请修改脚本中的 LRELEASE / LUPDATE。

3. 构建与发布

执行 qmake 后编译；若 resources/translations/codeplanet_en.qm 存在，editor.pro 会自动复制到 bin/translations/。
发布安装包时需包含 translations/codeplanet_en.qm（与 CodeEditor.exe 同级的 translations 子目录，或依赖工程目录下的 resources/translations/ 路径）。

编码与 MSVC 注意事项

MSVC：src/editor/editor.pro 已全局启用 /utf-8；源码 UTF-8 保存；已移除 #pragma execution_character_set（二者不可同时使用）。
若出现 C4819：确认文件为 UTF-8；AST 模块错误信息使用英文 ASCII 字面量。
语言菜单项「中文」使用 QString::fromUtf8(u8"中文")，不经过 tr()。

用户可见行为

中文：卸载翻译器，显示 tr() 源文。
English：加载 codeplanet_en.qm；若加载失败，qWarning 输出路径且界面保持中文。
上次选择的语言保存在数据库键 ui/locale（DatabaseService，与 Ops 共用）；Launcher 首次启动默认 English，Ops 首次启动默认中文。
Launcher 窗口右上角 CH/EN 图标切换语言（显示当前语言）；与 Ops「工具 → 语言」写入同一 ui/locale。
Runtime：Launcher 点击「立即启动」时通过命令行 --locale=zh_CN|en 传入当前界面语言；Runtime 使用 UiLocaleService::applySessionLocale 只读应用、不回写 ui/locale，进程存活期间不受 Launcher 后续切换影响。

尚未国际化的范围

以下仍为硬编码中文或英文，后续可按同样模式扩展：

Runtime / Launcher 日志区 [main]、[runtime] 等运行消息（ intentionally ASCII 便于 grep）
格式检查/调试表格中的运行时消息（codeeditorwidget2.cpp 内拼接字符串）
部分调试日志与 qDebug 输出
插件与 FunctionLib.ini 中的函数描述

新增一种语言（扩展参考）

1. 复制 codeplanet_en.ts 为 codeplanet_xx.ts，翻译后 lrelease 得到 .qm。 2. 在 Application::setLocale 中增加 locale 分支与加载路径。 3. 在语言菜单增加对应 QAction。 4. 更新 scripts/generate_i18n.bat（或增加并行脚本）与 editor.pro 复制规则。

故障排查

现象	处理
选 English 仍为中文	确认 `bin/translations/codeplanet_en.qm` 或 `resources/translations/codeplanet_en.qm` 存在；查看控制台 `Failed to load English translation`
「中文」菜单乱码	确认使用 `QString::fromUtf8(u8"中文")`，勿用 `QStringLiteral("中文")`
编译 C3437	`/utf-8` 与 `#pragma execution_character_set` 冲突；工程已统一用 `/utf-8`，pragma 已全部删除
lrelease 找不到	使用完整路径或 `.\lrelease.exe`（PowerShell 当前目录执行）

---

维护者请在修改界面文案或 locale 逻辑后，同步检查本文与 docs/开发指南.md 中的「国际化」小节。

CodePlanet 软件帮助