Weblate 客户端

安装

Weblate 客户端 单独提供，包括 Python 模块。源代码在 WeblateOrg/wlc 仓库 进行维护。 要使用下面的命令，您需要使用 pip 安装 wlc：

pip install wlc

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

uvx wlc --help

提示

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

Docker 用法

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

Images are published on Docker Hub and the GitHub Container Registry. The examples below use the Docker Hub image name.

正在安装：

docker pull weblate/wlc

以下标签可用：

latest

最新稳定版.

Full version, for example 2.2.0

特定的稳定版.

Major version, for example 2

大版本中的最新稳定版.

edge

Current development version from the main branch.

edge-YYYY-MM-DD-COMMIT

A specific development snapshot.

To build an image from the source checkout:

docker build -t 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. The same pairing is required for the --allow-insecure-http and --allow-insecure-ssl overrides.

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. TLS certificates are always verified by default, including for loopback URLs. Use --allow-insecure-ssl or WLC_ALLOW_INSECURE_SSL only when certificate verification can not be enabled.

入门

最简单的入门方式是在 ~/.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 的旧配置。

在 2.2.0 版本发生变更: Global allow_insecure_http configuration is no longer supported. Configure an origin in the [insecure_http] section instead.

迁移旧配置：

[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 形式调用该命令行工具，Python API 见 wlc。

变量

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

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

指定输出格式。默认值是 text 。

--version

Print the program version and exit. The version command supports output formatting and can print only the version number.

--debug

Print verbose HTTP communication. Authorization header values are redacted and request bodies are not logged, but query parameters are; do not put secrets in query parameters.

--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. When the API URL comes from automatically discovered project configuration, this option requires --url.

--allow-insecure-ssl

Disable TLS certificate verification for the current run. Certificates are verified by default for every HTTPS URL, including loopback URLs. When the API URL comes from automatically discovered project configuration, this option requires --url.

--config PATH

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

--config-section SECTION

选择要使用的配置文件部分，而不是 [weblate] ，见 配置文件。

对象路径

Commands that operate on an object accept one of these paths:

PROJECT

项目标识串.

PROJECT/COMPONENT

部件标识串，包括其项目。

PROJECT/COMPONENT/LANGUAGE

翻译语言，包括其项目和部件。

UNIT_ID

Numeric translation unit ID. Only commands that explicitly support units accept this form.

Commands that require an object use the translation setting from 配置文件 when the path is omitted. The ls and download commands also use this setting before falling back to their no-object behavior. For list-components and list-translations, an omitted object always requests an instance-wide list.

命令

以下命令可用：

version

打印当前版本。

--bare

只打印版本号。

list-languages

列出 Weblate 中的所有语言。

list-projects

列出 Weblate 中的所有项目。

list-components

列出 Weblate 中的所有部件，或者特定项目中的部件。

list-translations

列出 Weblate 中的所有翻译，或者特定部件中的翻译。

list-units

列出特定翻译中的单元。

--query QUERY

Filters units using the search query syntax.

show

显示项目、部件、翻译或单元。

delete

没有确认提示就删除项目、部件、翻译或单元。

ls

未指定对象时列出所有项目，项目中的部件或部件中的翻译。

commit

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

pull

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

push

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

reset

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

cleanup

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

repo

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

stats

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

lock-status

显示部件的锁定状态。

lock

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

unlock

解锁 Weblate 部件的翻译。

changes

显示项目、部件或翻译的更改。

download

Downloads translation files. For a translation, wlc writes the file to --output or to redirected standard output. It refuses to write raw file content to an interactive terminal.

For a component or project, --output is required and is treated as a directory. wlc writes one ZIP archive per component. With no object, it downloads every component in the Weblate instance in the same way.

--convert FORMAT

Requests conversion to FORMAT on the server. If unspecified, no conversion happens.

--output PATH

Specifies the output file for a translation or output directory for a component, project, or instance-wide download. Use - to write a translation to standard output.

--no-glossary

Excludes glossary components from component, project, and instance-wide downloads.

upload

上传翻译文件。

--overwrite

Overwrites existing translated strings. This is equivalent to --conflicts replace-translated.

--conflicts {ignore,replace-translated,replace-approved}

选择如何处理与现有翻译的冲突。

--input PATH

Reads content from PATH. If unspecified or -, content is read from standard input.

--method {translate,approve,suggest,fuzzy,replace,source,add}

要使用的上传方法，参见 导入方式。默认为 translate 。

--fuzzy {process,approve}

选择模糊字符串（标记为需要编辑）的处理。

--author-name NAME

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

--author-email EMAIL

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

edit-unit

Updates a translation unit. At least one update option is required.

--target TARGET [TARGET ...]

设置一条或多条已翻译的字符串。

--state STATE

Sets the unit state: 0 for empty, 10 for fuzzy, 20 for translated, or 30 for approved.

--explanation EXPLANATION

设置字符串解释。

--extra-flags FLAGS

设置额外的字符串标记。

提示

您可以通过传递 --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 系统全局配置文件。

~/.config/weblate.ini

类 Unix 系统上的替代性全局配置文件名。

/etc/xdg/weblate

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

/etc/xdg/weblate.ini

替代性系统级备用文件名。

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

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

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

.weblate, .weblate.ini, weblate.ini

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

Project configuration is loaded after global configuration and overrides matching settings. It can select the API URL, default object, request settings, and a matching URL-scoped API key, allowing a cloned repository to automatically select its Weblate server and translation.

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

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

key

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

url

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

translation

Default object path for commands that accept one: a project, component, translation, or numeric unit ID.

retries, timeout, allowed_methods, backoff_factor, status_forcelist

HTTP request retry and timeout settings. retries defaults to 0 and backoff_factor to 0. status_forcelist is a comma-separated list of HTTP status codes that trigger retries and is empty by default.

allowed_methods lists methods that may be retried, separated by commas or whitespace. It defaults to HEAD, DELETE, OPTIONS, PUT, and GET. These retry settings are passed to urllib3.util.Retry.

timeout 是请求超时，单位为秒，默认值 300 。当前 wlc 版本使用 allowed_methods 替换旧的 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

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

Project configuration can also supply or replace a matching entry in [keys]. Do not commit valuable API keys to version control; normally keep keys in personal configuration and only the API URL and default object in project configuration.

Insecure transport exceptions are stored in origin-scoped sections in trusted user configuration:

[insecure_http]
http://legacy.example.com:80 = true

[insecure_ssl]
https://legacy.example.com:443 = true

An origin consists of the scheme, normalized hostname, and effective port. The API path is ignored, while different schemes and ports remain isolated. The [insecure_http] section allows API keys over non-local HTTP for matching origins. The [insecure_ssl] section disables TLS certificate verification for matching origins.

在 2.2.0 版本发生变更: TLS certificates are verified for all hosts by default. Insecure HTTP and TLS configuration is scoped to origins. Automatically discovered project configuration can neither add entries to these sections nor enable the removed global settings. User configuration and explicitly selected --config files are trusted.

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.

在 2.2.0 版本发生变更: Insecure HTTP and TLS environment overrides require WLC_URL when the API URL would otherwise come from automatically discovered project configuration.

也可用环境变量配置 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. When the API URL would otherwise come from automatically discovered project configuration, this variable is accepted only together with WLC_URL.

WLC_ALLOW_INSECURE_SSL

Set to 1, true, yes, or on to disable TLS certificate verification. Other values, such as 0 or false, are treated as unset. When the API URL would otherwise come from automatically discovered project configuration, this variable is accepted only together with WLC_URL.

The same protection applies to command-line arguments: --key, --allow-insecure-http, and --allow-insecure-ssl are 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 transport opt-ins are enable-only rather than normal precedence settings. They are enabled by a command-line or environment override, or by a matching origin in the trusted [insecure_http] or [insecure_ssl] section. Automatically discovered project configuration cannot add trusted origins.

安全模型

Project configuration is part of the repository workflow and is intentionally trusted to select the API endpoint, default object, request settings, and a matching URL-scoped API key. Running wlc inside a repository authorizes its nearest project configuration to select the server that receives commands and uploads and supplies displayed or downloaded content. Use an explicit trusted --config file when this is not desired.

The command-line client accepts API keys from --key, WLC_KEY, or the [keys] section. It does not load HTTP authentication from .netrc or the file named by NETRC. Credentials embedded in API URLs are rejected; use an API key instead. Other Requests environment integration, including proxy and CA-bundle variables, remains enabled.

The wlc threat model documents the complete trust boundaries, security properties, non-goals, and downstream responsibilities. A version-matched copy is included in source and wheel distributions. Report security issues using the Weblate vulnerability reporting process.

示例

打印当前程序版本：

$ wlc version

列出所有项目：

$ 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