python-qt-gui-zh

---
name: python-qt-gui-zh
description: 给没有多语言框架的 Python / Qt 开源桌面软件做中文界面补丁（双语标签、中文悬停说明、一键开启和还原）。用户说汉化某个开源软件、给它做中文界面、软件更新后中文没了时使用。以 VisoMaster Fusion 的补丁为实例。
---

# Python / Qt 开源软件汉化

实例代码在本仓库 `patch/` 和 `tools/`，照着改文件列表和变量名就能套到别的软件上。

## 1. 先找全界面文字藏在哪

截一张界面图，挑上面的字逐个在源码里搜。别信自己的「应该齐了」，一般有四种地方：

| 位置 | 长相 |
|---|---|
| 参数表字典 | `"label": "...", "help": "..."` |
| Qt Designer 生成的代码 | `QCoreApplication.translate("Win", u"...")`，文件名多是 `*_ui.py` / `main_window.py` |
| 业务代码里写死的 | `QAction("...")`、`.setText("...")`、`.setToolTip("...")` |
| 字典值、元组成员 | `{"diff": "Differencing Mask"}`、`("faces", "cbx", "Faces / Embeddings")` |

后加载的代码会用 `setText` 覆盖生成代码里的字，所以屏幕上那句和源码里搜到的那句可能不是同一处。先确认最后赋值的是谁。

## 2. 用 ast，不用正则

- `ast.literal_eval` 拿到真正的字符串值，单引号、转义引号、隐式拼接都认。
- `col_offset` 是 UTF-8 字节偏移。源码里有 `→`、`–` 这类字符时，在字节层面切片和拼接，从后往前替换。
- 写回去的字面量用 `json.dumps(zh, ensure_ascii=False)` 生成，别手写转义。
- 翻译模型可能把 `\n` 返回成两个字符，应用前先 `zh.replace("\\n", "\n")`。
- 写盘前 `ast.parse(新代码)`，报错就不写。

## 3. 哪些不能翻

- 程序拿来当 key 或 ID 比较的字符串（搜 `== "xxx"`、`.lower()` 后做 ID 的）
- 版本号、占位符、算法缩写
- 快捷键提示保留：`全屏 (Fullscreen)\tF11`
- 带换行的按钮标题用纯中文，双语会把按钮撑高

## 4. 形式

- 标签双语 `中文 (English)`，中文在前，方便截断时也认得出，英文留着搜教程。
- 悬停说明纯中文，这是用户最需要的。
- 窗口窄就改纯中文。先看用户实际的窗口宽度再定。

## 5. 翻译

- 量大就分批交给便宜的模型，标签 25 条一批，长说明 12 条一批，要求返回 JSON 数组并校验条数。
- 固定一张不翻的术语表（模型名、库名）。
- 每批写回磁盘，能断点续跑。后台翻译期间别改同一个 json。
- 同一个英文词全篇一个译法，翻完扫一遍。

## 6. 交付

- 第一次打补丁时把原文件存成 `.orig`，每次都从 `.orig` 重打，可以反复跑。
- 给用户两个 bat：开启、还原。bat 只写 ASCII 字符，用 CRLF 换行，中文输出交给 Python。
- 用一个**独立**的脚本统计覆盖率，别和提取器用同一套方法。
- 在上游最新版上试一遍：打补丁 → 全部能解析 → 还原 → `git status` 干净。

## 软件更新后

先还原英文，再跑 `tools/extract_*.py` 把新词追加进翻译表，补译后重新开启。不先还原的话，已经是中文的字会被当成新词。

• .gitignore 1 KB
• LICENSE 34 KB
• README.md 4 KB
• SKILL.md 3 KB