企业官网建设流程全解析

• 后端
• 前端
• 图像处理
• 人工智能
• AI 应用

导读

PhotoPrism 是一个 AI 驱动的照片管理应用，其前后端均通过 gettext 标准实现国际化（i18n）。本文以仓库中 assets/locales/README.md 为骨架，系统讲解 PhotoPrism 后端翻译体系的工作方式：从“可读英文消息即翻译 ID”的设计原则、占位符与复数格式，到 Poedit 的完整使用流程、新增语言与更新翻译的实操步骤，再到messages.pot的自动生成机制，并深入 pkg/i18n 源码与前端渲染逻辑，揭示后端消息如何借助messageId/messageParams在浏览器端按每个用户的语言实时渲染。读完本文，你将能独立为 PhotoPrism 后端维护、新增和发布多语言翻译。

一、PhotoPrism 的本地化架构：gettext 贯穿前后端

PhotoPrism 使用 gettext 这一被广泛采用的用户界面翻译标准来本地化前端与后端。其核心思路是：人类可读的英文消息（如File not found）直接作为查找翻译的 ID（msgid），在没有对应翻译时作为默认文案兜底。这意味着翻译 ID 不是晦涩的数字编号，而是本身可读、可维护的英文句子。

• 后端 Go 代码中，消息统一注册在 pkg/i18n/messages.go；
• 各语言的翻译存放在 assets/locales 下的子目录中，例如de/default.po对应德语、pt_BR/default.po对应巴西葡萄牙语；
• 前端 Vue 应用同样使用 gettext（vue3-gettext）在运行时把消息 ID 翻译成用户当前界面语言。

消息可能包含占位符，用于注入数字和其他变量。例如Found %d files中的%d、%s already exists中的%s，这类占位符在翻译时也必须保留，才能保证运行时参数正确替换。

事实依据：上述设计原则直接来自 assets/locales/README.md；占位符的实际使用可见 pkg/i18n/messages.go 中大量带%s、%d的消息定义。

二、什么内容需要翻译：通知与 API 响应

并非 PhotoPrism 的所有文案都需要翻译。README 明确指出，只有异步通知和特定 API 响应需要翻译以保证一致的用户体验；技术性日志消息应保持英文，以避免歧义和（即使是轻微的）错误翻译。

具体而言，面向用户的内容分两条路径渲染：

1. 异步通知与面向用户的 API 错误响应：由 Web 前端在每位用户当前的界面语言下渲染（基于消息 ID）。后端在响应中同时携带messageId（英文源字符串）和messageParams（参数），前端拿到后用本地 gettext 目录即时翻译；
2. default.po的后备作用：后端实例语言环境（locale）下服务端渲染的message/error字符串作为回退，供非浏览器消费者（如 CLI）使用。

这一“双轨”设计在 pkg/i18n/response.go 中有清晰的代码注释：Error/Message携带实例语言环境渲染好的字符串（供 CLI 等非浏览器端回退），MessageID与MessageParams携带未翻译的源字符串及其参数，使 Web UI 能以每位用户当前的语言环境渲染消息。

三、推荐工具：Poedit 的安装与定位

官方强烈推荐使用 Poedit 创建与更新翻译，其对 Mac、Windows、Linux 均免费。Poedit 的核心能力：

• 可视化编辑*.po文件，逐条展示“源字符串 ↔ 译文”；
• 自动生成二进制*.mo文件（提交到仓库时需一并提交*.mo）；
• 支持从 POT 文件更新已有翻译目录（Catalogue > Update from POT File...）。

仓库现状佐证：assets/locales 下每个语言目录均包含一个*.po文件，例如 assets/locales/de/default.po 头部包含X-Poedit-Basepath: .与Plural-Forms: nplurals=2; plural=n != 1;等 Poedit 生成的元信息，说明 Poedit 确实是官方维护翻译的工作流入口。

四、目录与文件规范：locale 命名与 default.po

assets/locales 下的每个子目录对应一种语言，目录名即该语言的locale（遵循 GNU 常用语言代码 与 locale 命名规范）：

每个目录中的翻译文件统一命名为default.po，这一点从 pkg/i18n/locales.go 中gotext.Configure(localeDir, string(locale), "default")的第三个参数即可印证——gotext 加载的 domain 名就是default。

locale 的规范化处理

pkg/i18n/locales.go 的SetLocale会对传入的 locale 字符串做规范化：

• 长度 2：小写处理，如DE→de；
• 长度 5：拆分为语言_地区并规范大小写，如pt-br→pt_BR；
• 其他：回退到Default（即英文en）。

随后gotext.Configure()会加载对应目录下的default.po/default.mo，从而实现运行时翻译。

五、新增一种语言：从 POT 到 default.po 的完整流程

按 README 指引，新增翻译的步骤如下：

1. 打开模板文件assets/locales/messages.pot；
2. 在 Poedit 底部点击"Create New Translation"，选择目标语言；
3. 开始逐条翻译；
4. 完成后，在 assets/locales 下新建一个以 locale 命名的目录（如ko、ja），把翻译保存为该目录下的default.po；
5. 同时提交 Poedit 自动生成的二进制*.mo文件（例如default.mo），因为 gotext 的Configure在读取目录时会同时解析default.po与default.mo。

更新已有翻译

对已存在的翻译应用新改动：在 Poedit 菜单中点击Catalogue > Update from POT File...，选择最新生成的messages.pot，Poedit 会合并新增/变更的 msgid，同时保留已有译文。

仓库证据：以 assets/locales/de/default.po 为例，其msgid "Something went wrong, try again"与 assets/locales/messages.pot 中的条目一一对应（#: messages.go:114引用相同的源码行号），且msgstr为德文翻译，可见 POT 与各 PO 文件之间严格同步。

六、POT 模板的自动生成：go generate 与 gettext

/assets/locales/messages.pot是翻译模板（提取自后端源码的全部 msgid）。它会在以下场景被自动更新：

• 在/pkg/i18n目录执行go generate；
• 或在项目根目录执行make generate（对应 Makefile 中的generate: go generate ./pkg/... ./internal/...目标，见 Makefile）。

生成机制的底层实现在 pkg/i18n/i18n.go：

//go:generate xgettext --no-wrap --language=c --from-code=UTF-8 --output=../../assets/locales/messages.pot messages.go

即通过xgettext从messages.go中提取所有gettext("...")调用，输出到assets/locales/messages.pot。

前置条件：此流程仅在系统安装了 gettext 工具链时才能工作。官方建议使用最新开发镜像（见 Developer Guide），因为开发镜像中预装了 gettext。

POT 文件结构（摘自 assets/locales/messages.pot）：

#: messages.go:114 msgid "Something went wrong, try again" msgstr ""

• #: messages.go:114是源码位置引用，标明 msgid 来自pkg/i18n/messages.go的哪一行；
• msgid是英文源字符串（即翻译 ID）；
• msgstr是译文，模板中为空；
• 带占位符的条目会标注#, c-format，例如msgid "%s already exists"。

七、后端实现原理：Message ID、参数替换与 API 响应

理解翻译体系后，再看 pkg/i18n 的源码实现，就能明白 README 描述的设计如何落地。

7.1 消息注册表：pkg/i18n/messages.go

所有后端消息以iota枚举定义Message类型的 ID，并映射到英文源字符串：

const ( ErrUnexpected Message = iota + 1 ErrBadRequest // ... MsgChangesSaved // ... ) var Messages = MessageMap{ ErrUnexpected: gettext("Something went wrong, try again"), ErrAlreadyExists: gettext("%s already exists"), // ... MsgEntriesAddedTo: gettext("%d entries added to %s"), }

从源码结构看，该注册表分为两组：Err*开头的是错误消息（如ErrFileNotFound、ErrUploadToServiceFailed、ErrInvalidPasscode、ErrMigrationInProgress等），Msg*开头的是信息/确认消息（如MsgImportCompletedIn、MsgIndexingFiles、MsgZipCreatedIn等），共覆盖 100 余条后端提示。

7.2 翻译与参数替换：pkg/i18n/i18n.go

核心 API 一览：

• Msg(id Message, params ...any) string：返回翻译后的消息字符串，先经 gotext 按当前 locale 翻译，再通过msgParams执行fmt.Sprintf风格的占位符替换；
• Error(id Message, params ...any) error：返回翻译后的错误对象；
• Source(id Message) string：返回未翻译的英文源字符串（msgid），这是前端用来按用户语言渲染消息的稳定键；
• Lower(id Message, params ...any) string：返回小写化的未翻译消息，用于日志，避免日志中出现各种语言混排。

7.3 双轨响应：pkg/i18n/response.go

NewResponse(code, id, params...)构造的Response同时携带三份信息：

code < 400时填充Message，否则填充Error；Success()方法依据Error == "" && Code < 400判断成功。

7.4 前端渲染闭环

前端在 frontend/src/common/api.js 中处理 API 错误时，会优先使用messageId渲染：

if (data.messageId) { // Render the backend message in the current UI locale from its source id and params. errorMessage = Tp(data.messageId, data.messageParams); }

Tp定义于 frontend/src/common/gettext.js：先用$gettext(msgid)在当前界面语言下翻译源字符串，再执行有序位置参数替换（正则匹配%s、%d等格式符）。通知组件 frontend/src/component/notify.vue 同样遵循“messageId优先、否则用message”的逻辑，登录页（frontend/src/page/auth/login.vue）还会从 session 存储中恢复session.messageId/session.messageParams以在刷新后重放认证错误提示。

由此形成完整闭环：后端按用户语言渲染（非浏览器端）+ 前端按各自 UI 语言渲染（浏览器端），这正是 README 所说“提供一致用户体验”的技术保障。

八、测试验证：翻译正确性的自动化保障

pkg/i18n 提供了完整的单元测试，可直接验证翻译机制：

• pkg/i18n/i18n_test.go：
  • TestMsg：验证ErrAlreadyExists在德语下翻译为"Eine Katze existiert bereits"，波兰语下为"Kot już istnieje"，巴西葡萄牙语下为"Gata já existe"，切换回空 locale 后恢复英文默认值；
  • TestSource：验证Source()始终返回未翻译的英文源字符串（"%s already exists"），不受SetLocale影响——这正是前端按用户语言渲染的前提；
  • TestError：验证Error()返回翻译后的错误文本；
  • TestLower：验证日志用的小写化消息不随 locale 变化。
• 其他：locales_test.go、response_test.go分别覆盖 locale 规范化和响应构造逻辑。

这些测试确认了“英文源字符串为稳定键、翻译随 locale 切换”的核心行为，是翻译贡献者提交新语言时的安全网。

九、翻译工作流小结与注意事项

注意事项：

1. 占位符（%s、%d）在译文中必须原样保留，否则运行时参数替换会错位；
2. *.mo是运行时读取的二进制格式，忘记提交会导致部分环境回退到英文；
3. POT 重新生成依赖系统安装 gettext，建议使用官方开发镜像；
4. 新增语言目录名必须符合 locale 命名规范（如pt_BR、zh_TW），因为 pkg/i18n/locales.go 的SetLocale会按长度 2 或 5 做规范化匹配。

结语

PhotoPrism 的后端翻译体系以 gettext 为统一标准，用“英文可读消息即 ID”的设计降低维护成本，通过 POT 模板 + 各语言default.po管理翻译，再以messageId/messageParams双轨机制实现“后端渲染兜底 + 前端按用户语言渲染”。掌握 assets/locales/README.md 描述的工作流，配合 pkg/i18n 源码与测试，你就能为 PhotoPrism 提供高质量、可验证的多语言支持。

• 后端
• 前端
• 图像处理
• 人工智能
• AI 应用