Weblate 客户端

安装

Weblate 客户端 单独提供，包括 Python 模块。要使用下面的命令，您需要使用 pip 安装 wlc：

pip install wlc

您也可以直接使用 uvx 执行它：

uvx wlc --help

提示

你可以将 wlc 用作 Python 模块，见 wlc。

Docker 用法

Weblate 客户端也可以用作 Docker 映像。

该映像发布在 Docker Hub：https://hub.docker.com/r/weblate/wlc

正在安装：

docker pull weblate/wlc

The Docker container uses Weblate Client defaults and connects to the API deployed on localhost. Configure the API URL and API key using the normal wlc arguments or environment variables, for example --url, --key, WLC_URL, and WLC_KEY. API keys are rejected over non-local http:// URLs by default; use HTTPS, loopback HTTP for local development, or explicitly opt in to insecure HTTP.

启动容器的命令使用以下语法：

docker run --rm weblate/wlc [WLC_ARGS]

示例：

docker run --rm weblate/wlc --url https://hosted.weblate.org/api/ list-projects

您可能希望将 配置文件 传递给 Docker 容器。仓库包含项目配置，如 .weblate 时，最简单的方法是将当前目录添加为 /home/weblate 卷：

docker run --volume $PWD:/home/weblate --rm weblate/wlc show

When the mounted repository provides the API URL in project configuration and you pass an unscoped API key to the container, also pin the URL explicitly: WLC_KEY requires WLC_URL, and --key requires --url.

If the configured API URL uses non-local http:// and an API key is provided, the container refuses to send the key unless insecure HTTP is explicitly enabled. Prefer HTTPS; for legacy deployments, pass --allow-insecure-http or set WLC_ALLOW_INSECURE_HTTP.

入门

最简单的入门方式是在 ~/.config/weblate 中创建个人 wlc 配置 (见 配置文件 了解完整恢复规则和其他位置)：

[weblate]
url = https://hosted.weblate.org/api/

[keys]
https://hosted.weblate.org/api/ = APIKEY

然后，您可以在默认服务器上调用命令：

wlc ls
wlc commit sandbox/hello-world

参见

配置文件

旧式设定

在 1.17 版本发生变更: 不再支持使用无作用域限定的 key 的旧配置。

迁移旧配置：

[weblate]
url = https://hosted.weblate.org/api/
key = YOUR_KEY_HERE

到 key 作用域限定为 API URL 的配置：

[weblate]
url = https://hosted.weblate.org/api/

[keys]
https://hosted.weblate.org/api/ = YOUR_KEY_HERE

概要

wlc [arguments] <command> [options]

命令实际上指示应该执行哪个操作。

说明

Weblate 客户端是一个 Python 库和命令行实用程序，可使用 Weblate 的 REST API 远程管理 Weblate。命令行实用程序可以作为 wlc 调用，并且内置在 wlc 上。

变量

程序接受以下参数来定义输出格式或使用哪个Weblate实例。这些变量必须位于任何命令之前。

--format {csv,json,text,html}

指定输出格式。

--url URL

指定 API URL。覆盖在配置文件中找到的任何值，请参阅 配置文件。该网址应以 /api/ 结尾，例如 https://hosted.weblate.org/api/。

--key KEY

指定要使用的 API 用户密钥。覆盖在配置文件中找到的任何值，请参阅 配置文件。您可以在 Weblate 的个人资料中找到密钥。当从自动发现的项目配置加载 API URL 时，--key 必必须和 --url 一起使用。默认拒绝非本地 http:// URL 的 API 密钥。

--allow-insecure-http

Allow sending API keys over non-local http:// URLs. Prefer HTTPS or loopback HTTP instead; this option is intended only for legacy deployments where HTTPS is not available. This option only enables insecure HTTP for the current run; omitting it does not disable allow_insecure_http from configuration.

--config PATH

只从 PATH 而不是从发现的全局和项目配置文件加载配置，见 配置文件。

--config-section SECTION

覆盖正在使用的配置文件部分，请参阅 配置文件。

命令

以下命令可用：

version

打印当前版本。

list-languages

列出 Weblate 中使用的语言。

list-projects

列出 Weblate 中的项目。

list-components

列出 Weblate 中的部件。

list-translations

列出 Weblate 中的翻译。

show

显示 Weblate 对象（翻译，部件或项目）。

ls

列出 Weblate 对象（翻译，部件或项目）。

commit

提交在 Weblate 对象（翻译，部件或项目）中所做的更改。

pull

拉取远程仓库的更改到 Weblate 对象中（翻译，部件或项目）。

push

将 Weblate 对象更改推送到远程仓库（翻译，部件或项目）。

reset

重置 Weblate 对象中的更改以匹配远程仓库（翻译，部件或项目）。

cleanup

删除 Weblate 对象中所有未跟踪的更改以匹配远程仓库（翻译，部件或项目）。

repo

显示给定 Weblate 对象（翻译，部件或项目）的仓库状态。

stats

显示给定 Weblate 对象（翻译，部件或项目）的详细统计数据。

lock-status

显示锁定状态。

lock

锁定部件以防止在 Weblate 中进一步翻译。

unlock

解锁 Weblate 部件的翻译。

changes

显示给定对象的更改。

download

下载翻译文件。

--convert

转换文件格式，如果未指定，则在服务器上不进行任何转换，并且将文件原样下载到仓库中。

--output

指定要保存输出的文件，如果未指定，则将其打印到 stdout。

upload

上传翻译文件。

--overwrite

上传时覆盖现有翻译。

--input

从中读取内容的文件，如果未指定，则从 stdin 中读取。

--method

要使用的上传方法，参见 导入方式。

--fuzzy

模糊（标记为需要编辑）的字符串处理（empty, process, approve）

--author-name

作者姓名，以覆盖当前经过身份认证的用户

--author-email

作者电子邮件，以覆盖当前经过身份认证的用户

提示

您可以通过传递 --help 获得有关调用单个命令的更多详细信息，例如：wlc ls --help 。

配置文件

当提供了 --config 时，wlc 只加载那个文件。

没有 --config，wlc 先从标准的平台特定的位置加载发现的全局配置文件：

C:\Users\NAME\AppData\Roaming\weblate.ini

Windows 漫游用户全局配置文件。

C:\Users\NAME\AppData\Local\weblate.ini

Windows 本地用户全局配置文件。

~/.config/weblate

类 Unix 系统全局配置文件。

/etc/xdg/weblate

系统作用域的备选配置文件。

该程序遵循 XDG 规范，因此您可以通过环境变量 XDG_CONFIG_HOME 或 XDG_CONFIG_DIRS 来调整配置文件的位置。

在 Windows 系统上，APPDATA 和 LOCALAPPDATA 是配置文件的首选位置。

加载全局配置后，wlc 从当前目录或其父目录加载最靠近的项目配置文件：

.weblate, .weblate.ini, weblate.ini

放在仓库中的项目配置文件。

只加载离得最近的项目配置。忽略较远父目录中的配置文件。

可以在 [weblate] 部分中配置以下设置（您可以通过 --config-section 进行自定义）：

key

Removed in version 1.17: 用 [keys] 部分指定作用域限定为单独 API URL 的 key，见 旧式设定。

url

API 服务器网址，默认为 http://127.0.0.1:8000/api/。

translation

默认翻译的路径 —— 部件或项目。

allow_insecure_http

Allow API keys over non-local http:// URLs, defaults to false. Loopback HTTP URLs, such as http://127.0.0.1:8000/api/, remain allowed for local development without this option. Prefer HTTPS instead of enabling this setting. Automatically discovered project configuration files cannot enable this option; set it in user configuration, an explicit --config file, WLC_ALLOW_INSECURE_HTTP, or --allow-insecure-http. The setting is cumulative: any trusted source that enables insecure HTTP is enough, and false or unset values from command-line or environment sources do not disable it.

retries, timeout, allowed_methods, backoff_factor, status_forcelist

传送给 urllib3 的可选 HTTP 重试和超时设置。使用 allowed_methods 列出可被重试的方法。当前的 wlc 版本使用这个设置名替代旧的 method_whitelist 选项。

配置文件是一个 INI 文件，例如：

[weblate]
url = https://hosted.weblate.org/api/
translation = weblate/application
retries = 3
allowed_methods = PUT,POST,GET
backoff_factor = 0.2
status_forcelist = 429,500,502,503,504
timeout = 30
allow_insecure_http = false

API 密钥存储在 [keys] 部分：

[keys]
https://hosted.weblate.org/api/ = APIKEY

这样，您就可以在版本控制系统仓库中使用 .weblate 配置时，将密钥存储在个人设置中，以便 wlc 知道它应该与哪个服务器通信。[keys] 查找范围限定于精确的 API URL。

In CI, unscoped keys must pin the API URL explicitly: set both WLC_URL and WLC_KEY, or use --url together with --key.

环境变量

Added in version 1.18.0.

在 2.0.1 版本发生变更: Unscoped API keys require an explicit API URL when project configuration is discovered automatically. API keys are rejected over non-local http:// URLs unless insecure HTTP is explicitly enabled.

也可用环境变量配置 API URL 和密钥。这对特定 CI 工作流（ WLC_URL 固定目的地， WLC_KEY 作为 secret 注入 ）尤其有用：

WLC_URL

API 网址

WLC_KEY

API key. When the API URL would otherwise come from automatically discovered project configuration, WLC_KEY is accepted only together with WLC_URL. API keys are rejected over non-local http:// URLs by default.

WLC_ALLOW_INSECURE_HTTP

Set to 1, true, yes, or on to allow API keys over non-local http:// URLs. Prefer HTTPS or loopback HTTP instead. Other values, such as 0 or false, are treated as unset and do not disable allow_insecure_http from configuration.

The same protection applies to command-line arguments: --key is accepted with automatically discovered project configuration only when --url is provided.

API URL 和 key 配置优先级（从高到低）为：

1. 命令行参数（--url、--key）。

2. 环境变量（WLC_URL、WLC_KEY）。

3. 未使用 --config 时，从 --config 或从发现的全局配置以及最靠近的项目配置进行加载。

The insecure HTTP opt-in is enable-only rather than a normal precedence setting. It is enabled when --allow-insecure-http is passed, when WLC_ALLOW_INSECURE_HTTP has a true value, or when allow_insecure_http is enabled in trusted configuration. Automatically discovered project configuration cannot enable it; set it in user configuration or pass an explicit --config file instead.

示例

打印当前程序版本：

$ wlc version
version: 0.1

列出所有项目：

$ wlc list-projects
name: Hello
slug: hello
url: http://example.com/api/projects/hello/
web: https://weblate.org/
web_url: http://example.com/projects/hello/

上传翻译文件：

$ wlc upload project/component/language --input /tmp/hello.po

您还可以指定 wlc 应该从事的项目：

$ cat .weblate
[weblate]
url = https://hosted.weblate.org/api/
translation = weblate/application

$ wlc show
branch: main
file_format: po
source_language: en
filemask: weblate/locale/*/LC_MESSAGES/django.po
git_export: https://hosted.weblate.org/git/weblate/application/
license: GPL-3.0+
license_url: https://spdx.org/licenses/GPL-3.0+
name: Application
new_base: weblate/locale/django.pot
project: weblate
repo: git://github.com/WeblateOrg/weblate.git
slug: application
template:
url: https://hosted.weblate.org/api/components/weblate/application/
vcs: git
web_url: https://hosted.weblate.org/projects/weblate/application/

通过此设置，可以轻松地提交当前项目中待处理的更改：

$ wlc commit