附加组件¶

附加组件提供了自定义和自动化翻译工作流程的方法。管理员可以从每个相应翻译项目或部件的管理 ↓ 附加组件菜单添加和管理附加组件。也可以在管理界面中进行全站范围的附加组件安装。

提示

您也可以使用 API、DEFAULT_ADDONS 或 install_addon 来配置附加组件。

触发附加组件的事件¶

附加组件安装¶

当附加组件被安装时触发。

部件更新¶

每当下列部件中发生更改时被触发：

仓库中字符串被改变。
添加了字符串。
添加了新翻译。

每天¶

每日触发，但附加组件通常根据 BACKGROUND_TASKS 设置在部件间分割每天的载荷。

添加并提交新翻译¶

新翻译被添加和提交后即刻触发。

提交更改后¶

提交更改后即刻触发。

推送仓库到上游后¶

仓库被推送到上游后即刻触发。

拉取新更改¶

每当新更改从上游被拉取后触发。

提交更改前¶

提交更改前触发。

推送仓库到上游前¶

在仓库被推送到上游之前。

尝试更新仓库¶

尝试更新仓库前触发。

文件解析¶

当文件被 Weblate 解析时触发。

保存字符串¶

字符串被保存后即刻触发。

保存新创建字符串¶

新建字符串被保存后即刻触发。

内置附加组件¶

自动翻译¶

附加组件 ID:

weblate.autotranslate.autotranslate

配置:

`mode`	自动翻译模式	可用选项： `suggest` -- 添加为建议 `translate` -- 添加为翻译 `fuzzy` -- 添加为"需要编辑"
`filter_type`	搜索筛选器	请注意，翻译所有字符串将丢弃所有现有的译文。可用选项： `all` -- 所有字符串 `nottranslated` -- 未翻译的字符串 `todo` -- 未完成的字符串 `fuzzy` -- 标记为需要编辑的字符串 `check:inconsistent` -- 未通过的检查：不一致 `check:translated` -- 未通过的检查：已被翻译
`auto_source`	自动翻译的来源	可用选项： `others` -- 其他翻译部件 `mt` -- 机器翻译
`component`	部件	输入要用作来源的部件的标识符，留空则使用当前项目中的所有部件。
`engines`	机器翻译引擎
`threshold`	匹配分数阈值

触发器:

附加组件安装, 部件更新, 每天

使用机器翻译或其他部件自动翻译字符串。

参见

自动翻译, 跨部件保持翻译一致

JavaScript 本地化 CDN¶

Added in version 4.2.

附加组件 ID:

weblate.cdn.cdnjs

配置:

`threshold`	译文阈值	包含的翻译的阈值。
`css_selector`	CSS 选择器	检测可本地化元素的 CSS 选择器。
`cookie_name`	语言 cookie 名称	存储语言偏好的 cookie 的名称。
`files`	从 HTML 文件中提取字符串	当前仓库或远程 URL 中要解析可翻译字符串的文件名列表。

触发器:

附加组件安装, 每天, 提交更改后, 拉取新更改

将译文发布到 JavaScript 或 HTML 本地化中使用的内容分发网络。

可以用于本地化静态 HTML 网页，或者在 JavaScript 代码中加载本地化文件。

为你的部件生成一个唯一的 URL，你可以将其包含在 HTML 页面中以本地化它们。详情见使用 Weblate CDN 翻译 HTML 和 JavaScript。

备注

此附加组件需在 Weblate 服务器上进行附加配置。LOCALIZE_CDN_PATH 配置生成的文件（在文件系统中）的写入位置，LOCALIZE_CDN_URL 定义从何处提供这些文件（URL）。Weblate 本身不提供这些文件，你必须设置外部源（通常使用 CDN 服务）。

此附加组件在 Hosted Weblate 上配置并通过 https://weblate-cdn.com/ 提供文件。

参见

配置 Weblate 内容分发网络附加组件, 使用 Weblate CDN 翻译 HTML 和 JavaScript, Weblate 内容分发网络的字符串提取, 使用 Weblate 内容分发网络对 HTML 进行本地化操作

移除空白字符串¶

Added in version 4.4.

附加组件 ID:: weblate.cleanup.blank
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 提交更改后, 拉取新更改

从翻译文件中删除没有译文的字符串。

使用此方法可以使翻译文件中不存在任何空字符串（例如，如果您的本地化库将它们显示为缺失，而不是退回到源字符串）。

参见

Weblate 除了更新翻译，还更新翻译文件吗？

清理翻译文件¶

附加组件 ID:: weblate.cleanup.generic
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 拉取新更改, 提交更改前

更新所有翻译文件以匹配单语言译文模版文件。对于大多数文件格式来说，这意味着移除译文模版文件中不再出现的旧翻译条目。

对于包含翻译字符串外的其他内容格式（如 HTML 文件、Windows RC 文件或 OpenDocument 格式），这也会使翻译文件与基文件同步。

参见

Weblate 除了更新翻译，还更新翻译文件吗？

添加缺少的语言¶

附加组件 ID:: weblate.consistency.languages
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 每天, 添加并提交新翻译

确保对一个项目内所有部件使用一致的一组语言。

每隔 24 小时，和在 Weblate 中加入新语言时，会检查一次缺失的语言。

不像其他多数附加组件，这个附加组件影响整个项目。

提示

用自动翻译自动翻译新添加的字符串。

部件发现¶

附加组件 ID:

weblate.discovery.discovery

配置:

`match`	用于匹配翻译文件的正则表达式
`file_format`	文件格式
`name_template`	自定义部件名称
`base_file_template`	指定单语种译文模版文件名	双语翻译文件请留空。
`new_base_template`	为新的翻译条目指定翻译模版文件	请指定模板文件，新语言的翻译文档将会套用该模板。对于 gettext 格式，请选择 .pot 文件。
`intermediate_template`	中间语言文件	中间翻译文件的文件名。在大多数情况下，这是开发者提供的翻译文件，用于创建实际的源字符串。
`language_regex`	语言筛选	扫描文件掩码时用于筛选翻译文件的正则表达式。
`copy_addons`	将主部件的附加组件克隆到新创建的部件
`remove`	删除不存在文件的部件
`confirm`	我确认上述匹配是正确的

触发器:

附加组件安装, 拉取新更改

根据版本控制系统中文件更改的情况来自动添加或删除项目部件。

该匹配是使用允许复杂配置的正则表达式完成的，但这样做需要一些知识。一些常见用例的示例可以在附加组件帮助部分找到。

匹配翻译文件的正则表达式必须包含两个命名组以匹配部件和语言，所有正则表达式的命名组均可用作模板字段中的变量。

您可以在所有文件名字段中使用 Django 模板标记，例如:

{{ component }}: 部件文件名匹配
{{ component|title }}: 首字母大写的部件文件名
{{ path }}: {{ component }}: 来自正则表达式的自定义匹配群

点击保存后，将显示匹配部件的预览，您可以从中检查配置是否真正符合您的需求：

{{ originalHierarchy }}: {{ component }}

匹配文件：

parent/module1/submodule/src/main/resources/ApplicationResources_fr.properties
parent/module1/submodule/src/main/resources/ApplicationResource_es.properties
parent/module2/src/main/resources/ApplicationResource_de.properties
parent/module2/src/main/resources/ApplicationResource_ro.properties

提示

部件发现附加组件使用 Weblate 内部网址。这是在多个部件之间共享版本控制系统设置的便捷方式。链接的部件使用主部件的本地仓库，其设置方法是将 weblate://project/main-component 填入各部件的源代码仓库字段（在管理 ↓ 设置 ↓ 版本控制系统)。这也节省了配置和系统资源的时间。

参见

模板标记, import_project

批量编辑¶

附加组件 ID:

weblate.flags.bulk

配置:

`q`	查询
`state`	要设置的状态	可用选项： `-1` -- 不要更改 `10` -- 需要编辑 `20` -- 已翻译 `30` -- 已核准
`add_flags`	要添加的翻译标记
`remove_flags`	要删除的翻译标记
`add_labels`	要添加的标签
`remove_labels`	要删除的标签

触发器:

附加组件安装, 部件更新

批量编辑标记、标签或字符串状态。

示例：

自动给新字符串添加标签¶
搜索查询	`NOT has:label`
要添加的标签	近期

将应用商店元数据文件所有更新日志字符串标记为只读¶
搜索查询	`language:en AND key:changelogs/`
要添加的翻译标记	`read-only`

将特定字符串标记为只读¶
搜索查询	source:r"^\`\`[.a-zA-Z0-9_-]*\`\`$" AND language:en
要添加的翻译标记	`read-only`

参见

批量编辑, 使用标记定制行为, 字符串标签

将未更改的译文标记为“需要编辑”¶

附加组件 ID:: weblate.flags.same_edit
配置:: 此附加组件无配置。
触发器:: 保存新创建字符串

每当从版本控制系统导入新的可翻译字符串并与源字符串匹配时，就会在 Weblate 中标记为需要编辑。对于包含未翻译字符串的源字符串的文件格式尤其有用。

提示

您可能还想通过在翻译标记中添加 strict-same 标记来加强未更改的译文检查。

参见

翻译状态

将新的源字符串标记为“需要编辑”¶

附加组件 ID:: weblate.flags.source_edit
配置:: 此附加组件无配置。
触发器:: 保存新创建字符串

每当一个新的源字符串从版本控制系统中导入时，它将在 Weblate 中被标记为需要编辑。这样就可以简单地筛选并编辑开发者编写的源字符串。

参见

翻译状态

将导入的新译文标记为“需要编辑”¶

附加组件 ID:: weblate.flags.target_edit
配置:: 此附加组件无配置。
触发器:: 保存新创建字符串

每当一个新的可翻译字符串从版本控制系统中导入时，它将在 Weblate 中被标记为需要编辑。这样就可以简单地筛选并编辑开发者创建的翻译。

参见

翻译状态

用原文填充只读字符串¶

Added in version 4.18.

附加组件 ID:: weblate.generate.fill_read_only
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 部件更新, 每天

将源字符串内容用作只读字符串的译文。

统计数据生成器¶

附加组件 ID:

weblate.generate.generate

配置:

`filename`	所生成文件的名称
`template`	所生成文件的内容

触发器:

提交更改前

生成一个包含关于翻译状态详细信息的文件。

你可以在文件名和内容中使用 Django 模板，详细的标记说明请参见模板标记。

例如为每个翻译生成一个摘要文件：

所生成文件的名称

locale/{{ language_code }}.json

内容

{
   "language": "{{ language_code }}",
   "strings": "{{ stats.all }}",
   "translated": "{{ stats.translated }}",
   "last_changed": "{{ stats.last_changed }}",
   "last_author": "{{ stats.last_author }}",
}

参见

模板标记

用原文预填充译文¶

Added in version 4.11.

附加组件 ID:: weblate.generate.prefill
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 部件更新, 每天

用源字符串填充翻译字符串。

部件中所有未翻译的字符串将被填充为源字符串，并被标记为需要编辑。当你的翻译文件中不能兼容空字符串时请使用这个功能。

假语言环境（Pseudolocale）生成¶

Added in version 4.5.

附加组件 ID:

weblate.generate.pseudolocale

配置:

`source`	源字符串
`target`	目标译文	此翻译中的所有字符串都将被覆盖
`prefix`	固定的字符串前缀
`var_prefix`	可变的字符串前缀
`suffix`	固定的字符串后缀
`var_suffix`	可变的字符串后缀
`var_multiplier`	可变部分乘数	可变部分重复多少次取决于源字符串的长度。
`include_readonly`	包含只读字符串

触发器:

附加组件安装, 部件更新, 每天

通过向源字符串添加前缀和后缀自动生成翻译。

伪 locale 对于查找未准备好进行本地化的字符串很有用。这是通过修改所有可翻译的源字符串来实现的，使得在用伪 locale 语言运行应用程序时很容易发现未修改的字符串。

也可以查找其本地化对应项可能不适合布局的字符串。

使用可变部分可以寻找那些在本地化后可能不适合用户界面的字符串-它根据源字符串的长度来扩展文本。可变部分是以文本的长度乘以乘数来重复的。例如 Hello world 带有可变后缀 _ 和变量乘数1将变为 Hello world___________ - 后缀在源字符串中的每个字符后都重复一次。

将使用以下模式生成字符串：

固定字符串前缀可变字符串前缀源字符串可变字符串后缀固定字符串后缀

提示

可以使用真正的语言进行检测，但在 Weblate 中有专用的假语言环境——en_XA 和 ar_XB。

提示

您可以使用此附加组件来开始翻译到现有语言或类似语言的新语言环境。将翻译添加到部件后，请遵循附加组件。示例： 如果您有 fr 的翻译并想开始翻译 fr_CA，只需将 fr 设置为源，将 fr_CA 设置为目标，并将前缀和后缀留空。

一旦您有新的翻译填重，请卸载附加组件，以防止 Weblate 更改复制后的翻译。

在注释中添加贡献信息¶

附加组件 ID:: weblate.gettext.authors
配置:: 此附加组件无配置。
触发器:: 提交更改前

更新 PO 文件标头的注释部分，以包含贡献者名字和贡献年份。

PO 文件标头如下所示：

# Michal Čihař <michal@weblate.org>, 2012, 2018, 2019, 2020.
# Pavel Borecki <pavel@example.com>, 2018, 2019.
# Filip Hron <filip@example.com>, 2018, 2019.
# anonymous <noreply@weblate.org>, 2019.

更新“配置文件”中的 ALL_LINGUAS 变量¶

附加组件 ID:: weblate.gettext.configure
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 每天, 添加并提交新翻译

当新的翻译添加时，更新 configure、configure.in 或任何 configure.ac 文件中的 ALL_LINGUAS 变量。

自定义 gettext 输出¶

附加组件 ID:

weblate.gettext.customize

配置:

width

自动换行

默认情况下 gettext 会在每行第 77 个字符处与换行符处换行。添加 --no-wrap 参数后，换行只在换行符处发生。

可用选项：

77 -- 在 77 个字符和换行符处换行（xgettext 默认）

65535 -- 只在换行符处换行（如'xgettext --no-wrap'）

-1 -- 不换行

触发器:

文件解析

允许自定义 gettext 的输出行为，例如是否启用自动换行。

它提供以下选项：

在第 77 个字符处和换行符处换行
仅在换行符处换行
不换行

备注

默认情况下 gettext 会在每行第 77 个字符处与换行符处换行。添加 --no-wrap 参数后，换行只会在换行符处发生。

更新 LINGUAS 文件¶

附加组件 ID:: weblate.gettext.linguas
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 每天, 添加并提交新翻译

添加新的翻译时更新 LINGUAS 文件。

生成 MO 文件¶

附加组件 ID:

weblate.gettext.mo

配置:

`path`	生成的 MO 文件的路径	如未指定，将使用 PO 文件对应的位置。
`fuzzy`	包括需要编辑的字符串	需要编辑的字符串（fuzzy）通常无法直接被用作译文。

触发器:

提交更改前

为每个变更的 PO 文件自动生成 MO 文件。

生成的 MO 文件的位置可以定制化，并且其字段使用模板标记。

备注

如果译文被移除，其 PO 文件将从仓库中被删除，但此附加组件生成的 MO 文件不会被删。必须手动从上游移除 MO 文件。

更新 PO 文件以匹配 POT 文件 (msgmerge)¶

附加组件 ID:

weblate.gettext.msgmerge

配置:

`previous`	保持已翻译字符串先前的 msgid
`no_location`	删除翻译字符串的位置
`fuzzy`	使用模糊匹配

触发器:

附加组件安装, 拉取新更改

使用 msgmerge 来更新所有的 PO 文件（如文件掩码所配置），而与 POT 文件（如新语种的翻译模版所配置）匹配。

多数 msgmerge 命令行选项可通过附加组件配置进行设置。

参见

Weblate 除了更新翻译，还更新翻译文件吗？

挤压 Git 提交¶

附加组件 ID:

weblate.git.squash

配置:

squash

挤压提交

可用选项：

all -- 所有提交并成一个提交

language -- 按语言

file -- 按文件

author -- 按作者

append_trailers

在挤压的提交说明附上尾注

尾注行是类似于 RFC 822 电子邮件标头的行，位于提交说明的其他自由格式部分的末尾，例如 “Co-authored-by: …”。

commit_message

提交说明

将使用此提交说明来代替挤压提交的组合提交说明。

触发器:

附加组件安装, 提交更改后

在推送变更之前挤压 Git 提交。

在推送变更之前，可以通过以下任一模式挤压 Git 提交：

所有提交成一个
每种语言
每个文件
每位作者

原始提交说明保留，但其作者信息丢失，除非选择每位作者，或者定制提交说明来包括它。

可以选择使用自定义提交说明覆盖原始提交说明。

可以选择从原始提交说明中删除尾注（像 Co-authored-by: … 这样的提交行），并附在挤压的提交说明的末尾。这也会为每位译者产生合适的 Co-authored-by: 记录。

自定义 JSON 输出¶

附加组件 ID:

weblate.json.customize

配置:

sort_keys

对 JSON 键排序

indent

JSON 缩进

style

JSON 缩进风格

可用选项：

spaces -- 空格

tabs -- 制表符

触发器:

文件解析

允许调整 JSON 的输出行为，例如缩进或排序。

格式化 Java 属性文件¶

附加组件 ID:

weblate.properties.sort

配置:

case_sensitive

对键排序启用大小写

触发器:

提交更改前

对 Java 属性文件进行格式化和排序。

将换行符合并到 Unix 换行符。
Unicode 转义序列的大写格式（如果存在）。
去除空白行和注释。
按键对字符串进行排序。
删除重复的字符串。

陈旧评论删除¶

附加组件 ID:

weblate.removal.comments

配置:

age

要保持的天数

触发器:

附加组件安装, 每天

设置删除评论的时间。

这可以用于删除可能已经过时的陈旧评论。小心使用，因为评论变旧并不意味着它们已经失去了重要性。

陈旧建议删除¶

附加组件 ID:

weblate.removal.suggestions

配置:

`age`	要保持的天数
`votes`	投票阈值	移除阈值。当投票被禁用时该项无效果。

触发器:

附加组件安装, 每天

设置删除建议的时间。

可与建议投票（参见同行评审）结合使用，用于删除在给定时间内未获得足够赞成票的建议。

更新 RESX 文件¶

附加组件 ID:: weblate.resx.update
配置:: 此附加组件无配置。
触发器:: 附加组件安装, 拉取新更改

更新所有翻译文件以匹配上游单语言译文模版文件。未使用的字符串将被删除，新字符串将复制源字符串添加。

提示

如果只想删除陈旧的翻译键，那么使用清理翻译文件。

参见

Weblate 除了更新翻译，还更新翻译文件吗？

自定义 XML 输出¶

Added in version 4.15.

附加组件 ID:

weblate.xml.customize

配置:

closing_tags

包括空白 XML 标记的结束标记

触发器:

文件解析

允许调整 XML 输出行为，例如关闭标签。

自定义 YAML 输出¶

附加组件 ID:

weblate.yaml.customize

配置:

indent

YAML 缩进

width

自动换行

可用选项：

80 -- 在 80 个字符处换行

100 -- 在 100 个字符处换行

120 -- 在 120 个字符处换行

180 --在 180 个字符处换行

65535 -- 不换行

line_break

换行符

可用选项：

dos -- DOS (\r\n)

unix -- UNIX (\n)

mac -- MAC (\r)

触发器:

文件解析

允许调整 YAML 的输出，例如自定义缩进或自定义换行。

定制附加组件列表¶

附加组件列表由 WEBLATE_ADDONS 配置。要添加其他附加组件，只需在这个设置中包含绝对类名称即可。

编写附加组件¶

你也可以编写自己的附加组件，创建一个 weblate.addons.base.BaseAddon 的子类来定义附加组件元数据，然后实现一个回调来执行处理。

参见

开发附加组件

从附加组件执行脚本¶

附加组件还可以用于执行外部脚本。这曾经集成在 Weblate 中，但现在必须写一些代码，将脚本包裹在附加组件中。

# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""Example pre commit script."""

from django.utils.translation import gettext_lazy

from weblate.addons.events import AddonEvent
from weblate.addons.scripts import BaseScriptAddon


class ExamplePreAddon(BaseScriptAddon):
    # Event used to trigger the script
    events: set[AddonEvent] = {
        AddonEvent.EVENT_PRE_COMMIT,
    }
    # Name of the addon, has to be unique
    name = "weblate.example.pre"
    # Verbose name and long description
    verbose = gettext_lazy("Execute script before commit")
    description = gettext_lazy("This add-on executes a script.")

    # Script to execute
    script = "/bin/true"
    # File to add in commit (for pre commit event)
    # does not have to be set
    add_file = "po/{{ language_code }}.po"

安装方法请参见定制的质量检查、附加组件和自动修复。

对于任何给定的部件，当前路径设置为版本控制系统仓库的根目录时，执行脚本。

此外，以下环境变量是可用的：

WL_VCS¶: 使用的版本控制系统。

WL_REPO¶: 上游仓库 URL。

WL_PATH¶: 版本控制系统仓库的绝对路径。

WL_BRANCH¶: 当前部件配置的仓库分支。

WL_FILEMASK¶: 当前部件的文件掩码。

WL_TEMPLATE¶: 单语言翻译模板的文件名（可以为空）。

WL_NEW_BASE¶: 建立新的翻译所使用文件的文件名（可以为空）。

WL_FILE_FORMAT¶: 用于当前部件的文件格式。

WL_LANGUAGE¶: 当前处理的翻译的语言（对于部件级别的钩子不可用）。

WL_PREVIOUS_HEAD¶: 更新后的上个 HEAD (仅在运行更新后钩子后可用)。

WL_COMPONENT_SLUG¶: 部件标识串用于构建 URL。

WL_PROJECT_SLUG¶: 项目标识串用于构建 URL。

WL_COMPONENT_NAME¶: 部件名称。

WL_PROJECT_NAME¶: 项目名称。

WL_COMPONENT_URL¶: 部件 URL。

WL_ENGAGE_URL¶: 项目参与 URL。

参见

部件配置

更新后仓库处理¶

可用于在 VCS 上游源更改时更新翻译文件。为了实现这个功能，请记住 Weblate 只能看到提交给版本控制系统的文件，所以您需要将更改作为脚本的一部分提交。

例如，使用 Gulp，您可以使用以下代码来实现：

#! /bin/sh
gulp --gulpfile gulp-i18n-extract.js
git commit -m 'Update source strings' src/languages/en.lang.json

翻译的预提交处理¶

在将翻译提交到仓库之前，使用 commit 脚本自动更改翻译。

它作为组成当前翻译文件名的单一参数而通过。

附加组件活动记录¶

附加组件活动记录保留附加组件执行的踪迹且可用来了解附加组件的活动。

可以在一定时间间隔后清除记录，方法是配置 ADDON_ACTIVITY_LOG_EXPIRY。