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.

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

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.

入门¶

最简单的入门方式是在 ~/.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¶: Specify the API user key to use. Overrides any value found in the configuration file, see 配置文件. You can find your key in your profile on Weblate. When the API URL is loaded from automatically discovered project configuration, --key must be used together with --url.

--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: 默认翻译的路径 —— 部件或项目。

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

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

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

This allows you to store keys in your personal settings, while using the .weblate configuration in the VCS repository so that wlc knows which server it should talk to. The [keys] lookup is scoped to the exact 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.

The API URL and key can also be configured using environment variables. This is especially useful for CI workflows where WLC_URL pins the destination and WLC_KEY is injected as a 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.

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

配置优先级（从高到低）为：

命令行参数（--url、--key）。
环境变量（WLC_URL、WLC_KEY）。
未使用 --config 时，从 --config 或从发现的全局配置以及最靠近的项目配置进行加载。

示例¶

打印当前程序版本：

$ 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