企业官网建设流程全解析

• 桌面应用

本文围绕开源仓库 CONTRIBUTING.md 展开，系统讲解 Foliate（一款基于 GJS 与 GTK4/Libadwaita 的电子书阅读器）的贡献开发全流程：从开发环境搭建、代码风格与 ESLint 规则、Issue/PR 工作流，到基于po/目录的本地化翻译协作。读完本文，你将掌握如何在本地编译运行 Foliate、写出符合项目规范的 GJS 代码、提交一份整洁的 Pull Request，并参与多语言翻译。

一、项目技术栈与贡献者须知

Foliate 是使用GJS（GNOME JavaScript 绑定）+ GTK4 + Libadwaita构建的 GTK 应用，渲染层依赖WebKitGTK 6.0（书籍内容在 WebView 中呈现）。这意味着贡献者必须熟悉现代 JavaScript（ES6+）在 GNOME 平台上的开发模式，而不是传统的 C 语言 GTK 开发方式。

从 meson.build 可以看到项目的构建基线：meson_version: '>= 0.59.0'，当前项目版本为3.3.0，并可通过check_runtime_deps选项在配置阶段校验运行时依赖的最低版本：

if get_option('check_runtime_deps') dependency('gjs-1.0', version: '>= 1.82') dependency('gtk4', version: '>= 4.12') dependency('libadwaita-1', version: '>= 1.8') dependency('webkitgtk-6.0', version: '>= 2.40.1') endif

二、首次开发：环境搭建与依赖安装

CONTRIBUTING.md 明确指出，搭建开发环境前需要先安装以下核心依赖：

结合 README.md 可以补全版本要求与各发行版的包名差异：运行时要求gjs >= 1.82、gtk4 >= 4.12、libadwaita >= 1.8（Debian 系对应gir1.2-adw-1）、webkitgtk-6.0（Fedora 包名为webkitgtk6.0，Debian 系为gir1.2-webkit-6.0）。另有三个可选依赖：

• 连字符断词：安装 hyphenation 规则包（如hyphen-en、hyphen-fr），用于自动断词排版；
• 文本转语音：安装speech-dispatcher及输出模块（如espeak-ng）；
• 文件追踪：安装tracker >= 3（Debian 系gir1.2-tracker-3.0）与tracker-miners，用于追踪电子书文件位置。

2.1 获取源码

仓库使用git submodules（src/foliate-js是捆绑的第三方 JS 库），克隆时必须递归拉取子模块：

git clone --recurse-submodules https://github.com/johnfactotum/foliate.git

也可以直接从 Releases 页面下载.tar.xz源码包。

2.2 不构建直接运行

快速试运行或验证小改动，无需完整构建：

gjs -m src/main.js

注意：这种方式不会加载 GSettings schema，设置不会持久化保存。解决方法是先用glib-compile-schemas编译 data/com.github.johnfactotum.Foliate.gschema.xml，再通过环境变量指定 schema 目录启动：

glib-compile-schemas data GSETTINGS_SCHEMA_DIR=data gjs -m src/main.js

2.3 Meson 构建与安装

构建期还需要meson (>= 0.59)、pkg-config、gettext：

meson setup build sudo ninja -C build install

卸载使用sudo ninja -C build uninstall。若想免 root 安装到本地目录，可指定自定义 prefix：

meson setup build --prefix $PWD/run ninja -C build install GSETTINGS_SCHEMA_DIR=run/share/glib-2.0/schemas ./run/bin/foliate

三、代码风格与规范：保持代码库一致性的硬性要求

CONTRIBUTING.md 强调 "Consistency is key to keeping the codebase maintainable"。作为 GJS + GTK4/Libadwaita 项目，Foliate 的代码风格原则如下：

• 语言：使用现代 JavaScript（ES6+），尽量避免遗留语法；
• 缩进：使用4 个空格，禁止 Tab；
• 命名约定：
  • 类与 GNOME 组件使用PascalCase（如源码中的Adw.Application子类FoliateApplication，见 src/app.js）；
  • 变量与函数使用camelCase；
  • snake_case 一般避免使用，除非是与特定 GLib/GObject 属性交互所必需；
• 干净的 PR：提交前必须通过 lint，且不允许遗留被注释掉的代码块或console.log语句；
• UI 文件：编辑.ui（XML）文件时保持结构整洁，ID 命名要能体现组件用途（可参考 src/ui/ 下如book-viewer.ui、library.ui的命名习惯）。

3.1 ESLint 配置的实际约束

项目的 ESLint 配置位于 eslint.config.js，它是上述规范的可执行版本，值得逐条对照：

其中ignores: ['src/foliate-js']表明捆绑的第三方库不参与 lint；globals声明了imports与pkg这两个 GJS 特有的只读全局对象。开发依赖（@eslint/js、globals）记录在 package.json 中，可通过npm install安装后运行npx eslint自查。

四、工作流：如何高效地报告问题与提交改动

4.1 报告 Bug 与开启 Issue

• 先搜索：打开 Issue 前先确认问题是否已被报告。项目维护者强烈建议先阅读 docs/faq.md 和 docs/troubleshooting.md——你的问题可能已有文档化的解决方案或变通方法。
• 信息具体：提供操作系统版本、Foliate 版本（Flatpak / 仓库构建等来源）以及可复现步骤。
• 快速获取调试信息：打开应用主菜单，进入About（关于）> Troubleshooting > Debugging Information，点击Copy Text即可一键复制系统和版本信息。

这套调试信息导出机制在源码中真实存在：Adw.AboutDialog的debug_info属性由getDebugInfo()生成（见 src/app.js 与 src/app.js），其中包含操作系统名称与版本、桌面环境与会话类型（XDG_CURRENT_DESKTOP、XDG_SESSION_DESKTOP、XDG_SESSION_TYPE）、语言环境（LANG）、Foliate/GJS/GTK/Adwaita/GLib/WebKitGTK 各组件版本号，以及用户数据/缓存目录，极大方便了问题定位。

• 附带日志：如果应用崩溃，请在终端中运行com.github.johnfactotum.Foliate（Flatpak 环境）并附上输出。

4.2 提交功能或修复

• Fork 并创建分支：分支名要具描述性，例如fix/sidebar-overlap或feat/custom-fonts，用前缀区分修复与功能；
• 提交信息：使用清晰、祈使语态的写法，如Add support for OPDS catalogs（而不是I fixed some stuff）；
• 一个 PR 只做一件事：保持 Pull Request 聚焦，两个无关的修复请拆成两个独立 PR。

五、翻译指南：让 Foliate 覆盖更多语言

Foliate 的目标是"让每个语言的使用者都能无障碍使用"。本地化工作基于GNU gettext体系，全部翻译文件位于po/目录。

5.1 工作方式

• 工具：使用 Poedit 或直接手动编辑.po文件；
• 查找语言文件：在 po/ 目录下找到你的语言文件（例如pt_BR.po），仓库当前已收录包括zh_CN.po、zh_TW.po、ja.po、ko.po在内的 30+ 种语言；
• 初始化新语言：如果po/中没有你的语言，可从foliate.pot模板初始化：msginit --locale=你的语言代码 --input=po/com.github.johnfactotum.Foliate.pot（可用的语言代码清单见 po/LINGUAS）；
• 术语一致性：确保 "Metadata"、"E-book" 等技术术语与 GNOME 生态其余项目的译法保持一致。源码中的可翻译字符串通过 gettext 的_()包装，例如 src/app.js 中关于对话框的标题、注释等；translator-credits用于在"关于"对话框中展示译者名单。

5.2 测试翻译

编译项目后即可在界面中查看翻译效果（字符串的收集清单定义在 po/POTFILES，构建脚本见 po/meson.build）。翻译文件在构建时通过i18n模块处理，提交翻译前建议本地完整跑一次构建，确认无语法错误且译文在 UI 中显示正常。

六、综合自检清单

提交 PR 前，对照以下清单逐项确认：

1. 代码：通过npx eslint（规则见 eslint.config.js），无注释掉的代码块，无console.log；
2. 缩进与命名：4 空格缩进，类用 PascalCase、变量/函数用 camelCase，.ui文件 ID 命名有意义；
3. 提交：分支名与提交信息清晰、祈使语态、一个 PR 一个主题；
4. 文档：涉及的行为变化已同步更新 docs/faq.md 或 docs/troubleshooting.md；
5. 本地化：新 UI 字符串已接入 gettext（_()包装），相关语言的.po文件已更新。

遵循上述规范，你的贡献将顺利融入这个 GJS + GTK4/Libadwaita 生态的优秀开源电子书阅读器。

• 桌面应用