Development.zh_CN

🌐 English · Deutsch · Español · Français

开发

本页介绍如何为 app/ 本身搭建本地开发环境——而不是安装（运行打包好的桌面版）或部署（运行容器化的生产形态）。请先阅读架构，了解各个部分是如何组合在一起的。

入门

npm install                 # 安装工作区（app/ + packages/gramps-date）
cp app/.env.example app/.env.local   # 指向一个正在运行的 gramps-web-api 实例
npm run dev -w app          # 启动 Vite 开发服务器

app/ 需要一个真正的 gramps-web-api 后端与之通信——它是一个纯客户端，没有模拟数据模式。最轻量的选择是 dev-fixtures/layer2-local-cache/api-fixture-example/setup.sh（见下文的开发测试环境）。

每个测试环境都在与测试环境脚本相同的 Python 环境中，从源码检出运行 gramps-web-api，因此该环境需要：

pip install -e ~/gramps/gramps --no-deps          # gramps 本身
pip install -e ~/gramps/gramps-web-api --no-deps  # + 它的依赖，见下
python3 deploy/webapi-requirements.py ~/gramps/gramps-web-api/pyproject.toml \
  | pip install -r /dev/stdin

gramps-web-api 的 const.py 在导入时会执行 gi.require_version("Gtk", "3.0")，因此必须同时具备真正的 PyGObject 和 GTK3 typelib（apt install python3-gi gir1.2-gtk-3.0，或 conda install -c conda-forge pygobject gtk3）；PyICU 是可选的，但它能消除一条本地化警告并修正姓名排序。

请注意，app/ 所依赖的 /api/<type>/query/ 端点已经合入 gramps-project/gramps-web-api 的 master 分支——较旧的分叉或分支对这些端点全都会返回 404。

开发测试环境

dev-fixtures/ 包含用于在本地运行 app/ 的真实 gramps-web-api 后端。它们不属于发布的产品——只是让本地开发无需自己手动配置服务器。运行脚本前请先阅读它——对于已有数据的家谱，它们都不是幂等的。每个测试环境都以 gramps/gramps 登录。

• layer2-local-cache/api-fixture-example/——最轻量的选择：一个运行在 :5002 上的纯 SQLite 实例，加载了 Gramps 自己的官方示例数据库 example.gramps，适合测试真实多样的日期（修饰符、质量、范围/区间）。在 app/.env.local 中设置 VITE_API_BASE=http://localhost:5002 即可指向它。实时同步同样适用于它，因为那只是对 /api/transactions/history/ 的一次轮询，与 Postgres 无关。
• layer2-local-cache/api-fixture/——另一个纯 SQLite 实例，加载的是 gramps-bench 生成的合成数据，用于在大家谱上做规模测试。
• layer3-sync/api-fixture/——一个以真正的 Postgres（SharedPostgreSQL）为后端的实例，适合测试多个写入者对同一棵家谱真正并发的编辑。app/.env.example 默认的 VITE_API_BASE 指向的就是它；除 SQLite 测试环境所需的一切外，它还需要一个正在运行的 Postgres 以及 SharedPostgreSQL 插件。

构建 Gramplet wheel

Gramplet 在浏览器中通过 Pyodide 运行 Python，依赖的是本地构建的 wheel；当这些 wheel 还不存在时，npm install 的 postinstall 步骤会跳过它们（并输出一行日志）——导致 Gramplet 在运行时报错 No known package with name 'gramps-gen-lib'。构建一次即可：

python3 scripts/build-stub-wheels.py    # 供 Pyodide 使用的 gi + orjson 替身
python3 scripts/build-gramps-wheel.py   # 把 gramps.gen.lib 构建为 Pyodide wheel
node app/scripts/copy-wasm.mjs          # 把它们注册到 public/pyodide/

测试

npm run test -w app         # Vitest：纯 store/同步逻辑，不做整个应用的渲染
npm run typecheck -w app    # tsc --noEmit
npm run test -w packages/gramps-date
pytest tests/               # GOQL 内置筛选预设 vs. 真正的 gramps-core 规则

pytest 测试套件（tests/gql_presets/，见其 README）会把每个内置的筛选器预设（app/src/data/gqlFilterPresets.ts）与它要移植的真正 gramps-core Rule 类进行比对，在 gramps-core 自带的示例家谱上运行——检查的不只是“能否编译”，而是“是否选出与桌面版规则相同的行”。需要能够导入 gramps/gramps-object-query-language（凡是能运行 gramps-web-api 的地方都已满足）；它自己的预设 JSON 快照会自动保持同步，无需额外步骤。

翻译

app/ 的界面字符串都经过 t()（app/src/i18n/i18n.ts），它沿用 gramps-web 自己的做法——一个简单的 {english: translated} 查找表，不使用 i18n 库——每种语言合并两个来源，在调用 setLanguage() 时选定，并缓存在内存中直到下一次切换语言：

• Gramps 桌面版的术语——按请求实时翻译：把实际用到的字符串 POST 到 gramps-web-api 已有的 GET/POST /api/translations/<lang> 端点，由它通过已安装的 gramps 包自己的 gettext 目录进行翻译。没有需要保持同步的静态副本；始终与服务器上安装的 gramps 版本一样新。要请求哪些桌面版术语字符串的固定列表位于 i18n.ts 的 desktopStrings 数组中——每当新包装的 t() 调用被证明是真正的 Gramps 术语、而不是 gramps-connect 特有的内容时，就手动逐条添加。
• gramps-web 自己的界面字符串，以及 Gramps 插件的字符串——由 scripts/bootstrap-translations.py 生成为静态的 app/public/lang/{locale}.json 文件（纳入 git 管理，这样应用无需任何人连接 Weblate 也能工作），该脚本读取 ../gramps-web/lang/ 和 ../addons-source/*/po/*-local.po——即本仓库旁边的同级检出，不涉及网络调用。每当这些同级检出更新、而您想刷新静态语料时运行它（python3 scripts/bootstrap-translations.py，需要 pip install polib）；它没有接入任何构建步骤，所以不会自动运行。可以放心重复运行：不加 --force 时它会跳过任何已存在的区域设置 .json，即使加了 --force，它也只会覆盖 app/public/lang/ 下的文件——没有网络调用，没有 git 操作，任何不好的结果都可以用一次 git checkout 撤销。

把应用自己更多的字符串包装进 t() 是一项持续、渐进的工作——app/scripts/wrap-translations.mjs 是一个一次性的 codemod（作为可复用工具保留下来），它机械地包装纯 JSX 文本和一个安全的属性白名单（label/title/placeholder）；凡是来自变量或对象字面量属性的内容（app/src/store/views.ts 中的视图/列配置、动态 API 数据、notifications.show() 调用），都需要在渲染它的组件中手动加上 t(...)。

参与贡献

讨论在 Gramps Discourse 论坛上进行；欢迎向 gramps-connect 仓库提交 issue 和 pull request。

许可证

AGPL-3.0-or-later，与 gramps-web-api 和 gramps-web 一致。packages/gramps-date 把 GPL-2.0-or-later 的 Gramps 核心代码翻译进本项目 AGPL-3.0-or-later 的代码库——这两种许可证如何结合，见它自己的 README（以及架构）。