与 Weblate 集成

Weblate 基础知识

项目和部件架构

在 Weblate 中,翻译被组织成项目和部件。每个项目可以包含多个部件,这些部件又包含各个语言的翻译。部件对应的是一个可翻译的文件(例如 GNU gettext PO (Portable Object)Android 字符串资源)。项目可以帮助您将部件组织成逻辑集合(例如,将一个应用中用到的所有翻译集合在一起)。

另外,可使用分类来组织项目内部件。部件可贵属于一个分类,且多个分类可被嵌套。

默认情况下,每个项目内都有对跨部件传播的公共字符串的翻译。这减轻了重复和多版本翻译的负担。但假如翻译应当有所不同,可以使用 允许同步翻译 通过 部件配置 禁用翻译传播。

仓库集成

Weblate 被构建为和上游版本控制仓库集成,持续本地化 描述了构建块以及更改如何在两者间流动。

参见

架构概览 描述了 Weblate 内部运行方式。

用户归因

Weblate 使用名字和电子邮箱在版本控制仓库中保留由译者恰当翻译的译文。将真实电子邮箱附加到提交遵循分布式版本控制精神并允许类似 GitHub 这样的服务将你在 Weblate 中的贡献关联到你的 GitHub 账户。

不过,此功能也会带来风险,公布在版本控制提交中的电子邮箱可能会被滥用。此外,一旦这样的提交公布在公开的代码托管平台(比如 GitHub),那么事实上便没有办法把它去掉。为了避免这种情况,Weblate 允许在 账户 中选择一个私密的提交邮箱。

因此,管理员在配置 Weblate 时应当考虑到这一点:

  • 应在服务条款中对电子邮箱的这种使用进行清晰描述,如果这样的文档是必需的。法律声明 可以提供帮助。

  • PRIVATE_COMMIT_EMAIL_OPT_IN 可以让电子邮箱默认处于私密状态。

将本地化项目导入 Weblate

Weblate 在开发时一直注意将版本控制系统集成作为核心功能。因此,最简单的方法是授予 Weblate 访问仓库的权限。导入过程将指导您将翻译配置进 Weblate 部件。

或者,您可以使用 Weblate 设置一个包含所有翻译的纯本地仓库,无需集成。

从 Weblate 获取更新的翻译

Weblate 将更新的字符串保存在一个数据库中并将它们提交到本地版本控制仓库。你可以将 Weblate 仓库添加为附加的远程仓库(当 Git 导出器 处于开启状态) 并从它那里获取翻译更新。

在这之前,您可能想要先提交任何在 Weblate 中所做的待处理的更改(请参见 惰性提交)。可以通过用户界面(在 仓库维护)或使用 Weblate 客户端 从命令行执行此操作。

如果你向 Weblate 授予了仓库的推送权限,并配置了 部件配置 中的 仓库推送 URL,此操作可以自动进行。见 推送 Weblate 的更改

或者,你也可以使用 Weblate 的 REST API 来更新翻译,让它们匹配来自你远程 VCS 仓库中上游的最新版本。

将远程更改获取到 Weblate

要将你远程 VCS 仓库中近期更新的任意字符串获取到 Weblate 中,请允许 Weblate 从上游仓库拉取。可以在用户界面(在 仓库维护)上或使用 Weblate 客户端 从命令行实现这一操作。

这可以通过在你的仓库中设置一个 webhook 来自动实现,每当有新的提交时,webhook 就会触发 Weblate。更多细节请参见 更新仓库

如果没用版本控制系统集成,你可以使用用户界面或 Weblate 的 REST API 来更新翻译让它们匹配你的 codebase。

添加新字符串

如您的翻译文件与代码一起存储在一个远程版本控制系统中,您很可能有一个现有的工作流供开发人员引入新的字符串。任何添加字符串的方法都将被采用,但请考虑使用 源字符串质量把关 以避免引入错误。

当翻译文件与代码分离时,可以通过以下方法将新字符串引入 Weblate。

  • 手动操作:从源语言内 工具 菜单使用 添加新的翻译字符串。你可以在表单内的 SingularPlural 之间做选择。选择要添加字符串的恰当形式。

  • 程序化地使用 API POST /api/translations/(string:project)/(string:component)/(string:language)/units/.

  • 通过上传源文件 替换现有翻译文件 (这将覆盖现有的字符串,所以请确保文件包括新旧字符串)或 添加新字符串,请参见 导入方式

备注

在 Weblate 中添加字符串需要 管理字符串

更新目标语言文件

对于单语言文件(请参见 支持的文件格式),Weblate 可以添加存在于 单语言译文模版语言文件 而不是实际翻译中的新翻译字符串。但它不自动清理陈旧的字符串,因为那可能会有难以预料的结果。如果你仍想做的话,请安装附加组件 清理翻译文件 ,它会根据您的要求处理清理工作。

Weblate 也不会尝试在原文更改时更新双语文件,所以如果需要 po 文件从 pot 被更新,请自行使用 更新源字符串导入方式 ,或使用 更新 PO 文件以匹配 POT 文件 (msgmerge) 附加组件来实现。

提示

源字符串提取工具,比如 xgettextlupdate,需要在 Weblate 之外执行。

引入新字符串

你可以在 管理字符串 开启时在 Weblate 中添加新字符串,但通常来说更好的做法是引入新字符串的同时,一并引入相应的代码更改。

单语言格式需要进行配置,以添加新字符串到 单语言译文模版语言文件。这通常由开发者完成,因为代码是这些人写的。你可能想要用 源字符串质量把关 引入对这些字符串的审校过程。

双语言格式通常使用某些工具(比如 xgettextintltool-update)从源代码中提取字符串。具体操作方法请参考你的本地化框架文档。一旦字符串被提取,可能需要额外步骤来更新现有的翻译,见 更新目标语言文件

提示

自动提取字符串功能目前不在 Weblate 考虑范围内。它通常涉及到执行不受信任的代码,这一点使该功能相对本地化平台而言,更适合通用的持续化代码集成服务。

你可能想把这个整合到你的持续化集成管道中让新的待翻译字符串自动出现。这样的管道也应覆盖 避免合并冲突

管理本地 VCS 仓库

Weblate 在其底层版本控制仓库中存储所有翻译。建议连接到远程仓库,但也可以设置纯本地仓库。仓库维护 允许控制此仓库。

提示

使用 持续本地化,任何更改都会自动从仓库推送,因此通常不需要手动管理它。

../_images/component-repository.webp