企业官网建设流程全解析

SimpleUI 是一款为 KOReader 电子书阅读器打造的高度可定制 UI 插件：专属主屏、底部导航栏、顶部状态栏和丰富的桌面小组件，让你一眼看到在读书籍、阅读统计与书架。这篇指南带你走通参与 SimpleUI 开源项目的完整路径——从提交 Bug 反馈、贡献语言翻译，到发出你的第一个代码 Pull Request（PR），每一步都附上了对应的文件位置。

🧭 先认识项目：轻量、无构建步骤的 Lua 插件

SimpleUI 是标准 KOReader 插件，用 Lua 编写，没有构建系统、不需要编译，源码直接运行——这正是它对新贡献者友好的原因。

项目由以下几类贡献方式构成，难度从低到高：

完整规则写在 CONTRIBUTING.md，项目总览见 README.md。插件入口是 main.lua，插件元信息（名称、版本 2.7.5、作者）在 _meta.lua。

🐛 第一步：Bug 反馈——把问题描述清楚

发现崩溃或界面异常？提交 Issue 时请包含以下 4 项，能大幅提高修复速度：

1. 清晰描述：发生了什么、你期望是什么
2. KOReader 版本号（菜单 → 帮助 → 关于中可见）
3. 设备型号（如 Kobo Libra 2、Kindle Paperwhite 5）
4. 复现步骤（如能复现）

如果 Bug 导致崩溃，KOReader 目录下的crash.log或reader.log日志非常有用，建议随 Issue 附上。

💡 报告前确认你安装的是最新 release 版本的simpleui.koplugin.zip，而不是从 "Code → Download ZIP" 下载的源码包——后者解压出的文件夹名带-main后缀，KOReader 无法识别为插件。

🌍 零代码贡献：给 SimpleUI 增加一种语言

翻译不需要任何编程知识，是最快上手的路径。翻译文件位于 locale/ 目录，目前已有 20+ 种语言，例如简体中文 locale/zh_CN.po、繁体中文 locale/zh_TW.po、日语 locale/ja.po 等。

新增语言的 4 步操作

1. 复制模板：把 locale/simpleui.pot 复制为locale/<语言代码>.po，使用标准 locale 代码（如de.po、fr.po、ko.po）
2. 打开编辑：用任意文本编辑器或 Poedit 等 PO 编辑器打开
3. 填写头部字段：Language-Team、Language、Plural-Forms等
4. 逐条翻译：为每条msgid填写msgstr，然后提交 PR

翻译条目形如下面这样，你只需填写msgstr：

msgid "Currently Reading" msgstr "Aktuell gelesen"

翻译者必须遵守的 3 条规则

• 永远不要修改msgid——只编辑msgstr
• 保留占位符：%d、%s、%%、\n必须原样出现在译文中（可以调序，不能删除）
• 拿不准就留空：msgstr留空时会自动回退显示英文原文

语言如何被加载的？插件启动时由 infra/sui_i18n.lua 读取 KOReader 的语言设置，先精确匹配pt_PT.po，再回退到语言前缀pt.po，最后回退英文——所以你提交的locale/<代码>.po文件名必须规范。

⚠️ 小提示：.po文件里一个未转义的引号就可能导致整个语言加载失败、界面退回英文。提交前可运行msgfmt --statistics -o /dev/null locale/<code>.po自检。

🔧 进阶：提交你的第一个代码 PR

获取代码并搭建测试环境

git clone https://gitcode.com/gh_mirrors/si/simpleui.koplugin

测试改动无需编译：把插件文件夹复制到 KOReader（或其模拟器）的plugins/目录，重启 KOReader 即可加载。KOReader 模拟器是最快的迭代方式，省去反复插拔真机。

改代码的规范流程

1. Fork 仓库后，为每个改动创建独立分支：git checkout -b fix/my-bug-description
2. 完成修改
3. 新增的用户可见文本必须用_()包裹，否则无法被翻译：

-- 正确 UIManager:show(InfoMessage:new{ text = _("Something went wrong.") }) -- 错误——不可翻译 UIManager:show(InfoMessage:new{ text = "Something went wrong." })

4. 如果引入了新字符串，用提取脚本重新生成翻译模板：

python3 scripts/extract_strings.py

该脚本会扫描全部 Lua 源码中的_()/N_()调用，重写 locale/simpleui.pot（脚本实现见 scripts/extract_strings.py） 5. 写清楚 commit message，推送分支并向main发起 PR

代码风格要点（PR 能否合入的关键）

• 跟随周边代码风格，优先使用local变量，避免污染模块级作用域
• 所有写入G_reader_settings的键必须使用simpleui_或navbar_前缀
• 用户数据文件放在插件目录之外（<KOReader 设置目录>/simpleui/），更新插件时才不会丢失
• 需要给 KOReader 类打补丁时，务必使用 infra/sui_patches.lua 提供的_acquireHooks/_releaseHooks钩子工具，并保证"开一本书、关一本书"多次循环后布局保持一致——这是该插件最容易出回归问题的地方

本地构建发布包（可选）

在项目根目录运行make build，会生成simpleui.koplugin.zip。scripts/Makefile 会自动排除开发文件和用户数据目录，模拟真实的发布流程，适合在 PR 前验证打包完整性。

✅ PR 提交前检查清单

发出 PR 前，逐项对照 CONTRIBUTING.md 中的清单：

• 改动在真机或 KOReader 模拟器上验证过
• 所有新 UI 字符串都用_()包裹
• 新字符串已加入 locale/simpleui.pot
• 新设置键使用了simpleui_或navbar_前缀
• 新用户文件存放在DataStorage/simpleui/而非插件目录内
• commit message 清晰描述了改动内容与原因
• 没有遗留调试日志或注释掉的死代码

无论是第一个 Bug Issue、一条翻译字符串，还是一段 Lua 补丁，每一份贡献都会让 SimpleUI 的主屏、导航栏与阅读体验更好用。打开仓库，从上面那张贡献方式表格里挑一行开始吧！