新增或修改功能
当你想给 Manga Translator 增加一个新功能（新的设置项、新的翻译器/OCR/渲染器选项、新的页面，或新的界面文案），或者修改一个现有功能时，这里说明从配置到界面再到运行时消费的完整开发路径。它不是架构总览（见架构与代码边界），也不展开测试方法论、打包发布或 HTTP API 的细节（分别见测试与代码质量、打包与发布以及 developer/http-api/ 下的页面）。
涉及的代码
- 这里仅处理“改代码后功能如何生效”的链路：配置模型 → 设置页挂载 → i18n → 持久化 → 后端消费 → 测试与人工验证。
- 桌面 UI、业务逻辑、服务层和后端流水线的具体模块边界见架构与代码边界；这里仅给出新增功能时每一层通常要改的文件。
- 新增 API 密钥、通道或轮询策略不在这里描述，见 API 管理页面；新增提示词文件、批量方案或富文本规则见对应的功能页。
- 这里不包含真实
.env、用户config.json、API Key、Token、用户名、私有绝对路径或私有提示词；示例默认值均来自仓库跟踪的模板与代码。
功能开发流程
新增或修改一个功能通常走下面的路径。不是每一步都必须改动：纯文案修改只改 i18n，纯后端算法改动可能不碰设置页；但新增一个“用户可配置参数”时，下面每一步都要检查。
flowchart TD
A["确定配置边界与 dotted key"] --> B["桌面/核心配置模型与默认值"]
B --> C["发行模板与持久化/参数导出"]
C --> D["设置页挂载与显示映射"]
D --> E["六种语言 label/description"]
E --> F["Web 默认值与管理员权限控件"]
F --> G["后端实际消费"]
G --> H["中英文 Wiki、Phase 0 与生成目录"]
H --> I["聚焦测试与实际界面验证"]
- 确定边界：先判断改动属于哪个模块——
desktop_qt_ui/（界面与业务逻辑）、manga_translator/（流水线与算法）、config/（发行模板）、locales/（文案）。 - 改配置模型：用户可配置项在
desktop_qt_ui/core/config_models.py的AppSettings子模型中加字段；后端运行时需要的配置在manga_translator/config.py的Config子模型中加字段。两者字段名、类型和默认值应保持一致。 - 同步发行模板：把新字段和默认值写进
config/config-example.json。桌面端启动优先级是用户config/config.json>config/config-example.json> Qt 模型默认值（见config_service.py）。 - 挂载设置页：在
desktop_qt_ui/ui/main_page/settings_tab_layout.json对应页签的items中追加配置键；页签标题本身也是 i18n key。 - 补显示映射：在
desktop_qt_ui/app_logic.py#get_display_mapping的labels中添加key -> label_*映射；有下拉选项时还要在get_options_for_key/get_display_mapping中提供选项与显示名。 - 加六语言 i18n 文案：
label_*标签和desc_*说明必须同时写入zh_CN、zh_TW、en_US、ja_JP、ko_KR、es_ES。非简体中文语言缺 key 时会回退显示简体中文，不能只补中英文。 - 确认持久化与参数导出：除
config_service.py的深合并外，还要检查保存默认 payload、区域参数数据类、导入过滤和后端导出字段；仅改 Pydantic 模型不保证编辑器链路会传值。 - 接后端消费：
manga_translator/config.py的Config读到新字段后，由manga_translator/manga_translator.py或对应模块（检测/OCR/翻译/修复/排版/超分/上色）真正消费。 - 接 Web 与管理员权限：确认
manga_translator/server/routes/config.py能提供默认值/选项；需要允许或隐藏参数时，在manga_translator/server/static/js/admin/components/permission-editor.js用createFormRow(..., section, key)添加控件，使禁用开关、用户组继承和collectFormData()共用完全一致的 dotted key。 - 同步中英文 Wiki：更新
doc/wiki/zh/与doc/wiki/en/的对应设置页面和reference/settings-index.md，记录默认值、生效条件、优先级、回退路径与实际消费阶段。 - 更新 Phase 0 字段证据：可见设置加入
doc/wiki/phase0-ui-parameter-fields.json；字段总数变化时同步verify_phase0_ui_parameter_fields.py与doc/wiki/scripts/build-settings-catalog.py的基线。 - 重新生成目录：运行设置与 i18n 生成脚本，生成
doc/wiki/data/settings.generated.json和i18n.generated.json，禁止手工编辑生成 JSON。 - 测试与界面验证：在
test/下写 pytest 风格回归脚本（首行import _bootstrap），用uv run --no-sync pytest运行。Web 管理控件需要实际渲染，确认字段控件与data-fullkey="section.key"禁用控件同时存在；语法检查不能替代界面验证。
添加 i18n 文案
界面文案统一走 desktop_qt_ui/locales/ 下的 JSON 语言包。I18nManager.translate(key) 先查当前语言；非回退语言缺 key 时会读取 zh_CN，zh_CN 也缺失时才返回 key 本身。因此遗漏日文、韩文、西班牙文或繁体中文翻译会在对应界面直接显示简体中文。
键有三种常见形态：
- 英文句子即 key：菜单、按钮、提示语等直接把英文文案当 key，例如
Settings、Export Config；en_US.json中 value 与 key 相同，zh_CN.json中放中文。 label_*：设置项名称，由get_display_mapping('labels')绑定到配置键，例如label_context_size。desc_*：设置说明面板的说明文字，格式为desc_{full_key}（点号换成下划线），例如desc_cli_context_size；缺失时说明面板显示“暂无说明”。
语言包包括 zh_CN、zh_TW、en_US、ja_JP、ko_KR、es_ES 六个；一次性脚本 scripts/add_batch_edit_locale_keys.py 演示了“缺则加、已有不动、en_US 用 key 自身”的批量补 key 方式。
Wiki 侧的 i18n 证据由 doc/wiki/scripts/build-i18n-catalog.mjs 从两个语言包生成到 doc/wiki/data/i18n.generated.json（--check 检查是否过期）；设置字段目录由 doc/wiki/scripts/build-settings-catalog.py 从 app_logic.py#get_display_mapping、发行模板和两个语言包生成到 doc/wiki/data/settings.generated.json。修改语言包后应重跑这两个脚本，不能手工改生成的 JSON。
约束与注意事项
- 新增用户可配置参数时，
config_models.py与manga_translator/config.py的字段名/类型必须一致，否则桌面端保存的值到后端可能对不上。 - 设置项标签走
get_display_mapping('labels')；漏加映射时，dynamic_settings.py会退回显示字段名（如min_box_area_ratio），不报错，但界面文案缺失。 desc_*说明缺失不会报错，说明面板显示“暂无说明”（Settings Desc No Description）。六种语言都要补齐；非简体中文语言缺 key 时会回退成简体中文。- 修改
settings_tab_layout.json会改变设置页的可见参数集合与分组；当前生成目录基线是 110 个可见字段，改动后应重新生成并核对 Phase 0 清单。 permission-editor.js的字段控件必须通过createFormRow(..., section, key)接入，否则管理员无法禁用该参数，用户组/用户继承也不会收集该 dotted key。- 不要手工修改
doc/wiki/data/生成目录，也不要读取或提交真实.env、用户config.json、密钥、令牌或私有绝对路径。
开发指南
选项中英对照
下面是与本页流程直接相关的界面文案（key → en_US 实际值 → zh_CN 实际值）：
| UI 调用 key | English 实际值 | 简体中文实际值 |
|---|---|---|
Settings | Settings | 设置 |
Settings Page Title | Settings | 参数设置 |
Settings Page Subtitle | Adjust translation pipeline parameters. Changes are saved automatically. | 调整翻译流程的各项参数。修改后将自动保存。 |
Settings Desc Header | Parameter Description | 参数说明 |
Settings Desc Key | Parameter Key: | 参数键： |
Settings Desc No Description | No description available. | 暂无说明。 |
Settings Desc Placeholder | Click any setting on the left to view details | 点击左侧任意设置项查看详细说明 |
Export Config | Export Config | 导出配置 |
Import Config | Import Config | 导入配置 |
General | General | 通用 |
OCR | OCR | 文字识别 |
Detection | Detection | 检测 |
Translation | Translation | 翻译 |
Inpainting | Inpainting | 修复 |
Typesetting | Typesetting | 排版 |
Mode Specific | Mode Specific | 模式相关 |
&Language | &Language | &语言 |
Language: | Language: | 语言： |
Apply | Apply | 应用 |
Save | Save | 保存 |
Cancel | Cancel | 取消 |
OK | OK | 确定 |
label_translator | Translator | 翻译器 |
label_context_size | Context Pages | 上下文页数 |
desc_cli_context_size | Translation context page count for multi-page joint translation. Larger values improve quality but consume more tokens. | 翻译上下文页面数，用于多页联合翻译。值越大翻译质量越好，但 token 消耗越多。 |
label_batch_concurrent | Concurrent Batch Processing | 并发批量处理 |
代码位置
| 层级 | 文件 | 本页核对内容 |
|---|---|---|
| 配置模型 | desktop_qt_ui/core/config_models.py、manga_translator/config.py | AppSettings / Config 子模型与默认值 |
| 发行模板 | config/config-example.json | Release 默认值与 get_default_config_path 引用 |
| 设置 UI | desktop_qt_ui/ui/main_page/settings_tab_layout.json、dynamic_settings.py、pages/settings_page.py | 页签分组、参数行、说明面板与语言刷新 |
| 显示映射 | desktop_qt_ui/app_logic.py | get_display_mapping、get_options_for_key、_t |
| i18n | desktop_qt_ui/services/i18n_service.py、locales/en_US.json、zh_CN.json | 六语言加载、缺 key 回退、key/实际值三列 |
| 持久化 | desktop_qt_ui/services/config_service.py | 优先级加载、逐键校验、用户配置同步 |
| 后端消费 | manga_translator/manga_translator.py、manga_translator/translators/__init__.py | 参数进入流水线、翻译器注册 |
| Web 配置与权限 | manga_translator/server/routes/config.py、manga_translator/server/static/js/admin/components/permission-editor.js | 默认值/选项暴露、字段控件、禁用开关与继承 dotted key |
| Wiki 字段证据 | doc/wiki/phase0-ui-parameter-fields.json、verify_phase0_ui_parameter_fields.py | 可见字段、控件类型、默认来源与字段基线 |
| 测试约定 | test/README.md、pyproject.toml | import _bootstrap、pytest 的 testpaths / pythonpath |
| Wiki 工具 | doc/wiki/scripts/build-i18n-catalog.mjs、build-settings-catalog.py | i18n 与设置目录的生成与检查 |