<a id="index-0"></a>

<a id="wlc"></a>

# Weblate 客户端

## 安装

[Weblate 客户端](https://pypi.org/project/wlc/) 单独提供，包括 Python 模块。源代码在 [WeblateOrg/wlc 仓库](https://github.com/WeblateOrg/wlc) 进行维护。 要使用下面的命令，您需要使用 pip 安装 **wlc**：

```sh
pip install wlc
```

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

```sh
uvx wlc --help
```

#### HINT
你可以将 **wlc** 用作 Python 模块，见 [`wlc`](https://docs.weblate.org/zh-cn/latest/python.md#module-wlc)。

<a id="docker-wlc"></a>

## Docker 用法

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

Images are published on [Docker Hub](https://hub.docker.com/r/weblate/wlc)
and the [GitHub Container Registry](https://github.com/WeblateOrg/wlc/pkgs/container/wlc). The examples below
use the Docker Hub image name.

正在安装：

```sh
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:

```sh
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`](#cmdoption-wlc-url),
[`--key`](#cmdoption-wlc-key), [`WLC_URL`](#envvar-WLC_URL), and [`WLC_KEY`](#envvar-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.

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

```sh
docker run --rm weblate/wlc [WLC_ARGS]
```

示例：

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

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

```sh
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`](#envvar-WLC_KEY) requires [`WLC_URL`](#envvar-WLC_URL), and [`--key`](#cmdoption-wlc-key) requires
[`--url`](#cmdoption-wlc-url). The same pairing is required for the
[`--allow-insecure-http`](#cmdoption-wlc-allow-insecure-http) and [`--allow-insecure-ssl`](#cmdoption-wlc-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`](#cmdoption-wlc-allow-insecure-http) or set [`WLC_ALLOW_INSECURE_HTTP`](#envvar-WLC_ALLOW_INSECURE_HTTP).
TLS certificates are always verified by default, including for loopback URLs.
Use [`--allow-insecure-ssl`](#cmdoption-wlc-allow-insecure-ssl) or [`WLC_ALLOW_INSECURE_SSL`](#envvar-WLC_ALLOW_INSECURE_SSL) only
when certificate verification can not be enabled.

## 入门

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

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

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

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

```console
wlc ls
wlc commit sandbox/hello-world
```

#### SEE ALSO
[配置文件](#wlc-config)

<a id="wlc-legacy"></a>

## 旧式设定

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

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

迁移旧配置：

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

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

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

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

## 概要

```text
wlc [arguments] <command> [options]
```

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

## 说明

Weblate 客户端是一个 Python 库和命令行实用程序，可使用 [Weblate 的 REST API](https://docs.weblate.org/zh-cn/latest/api.md#api) 远程管理 Weblate。以 **wlc** 形式调用该命令行工具，Python API 见 [`wlc`](https://docs.weblate.org/zh-cn/latest/python.md#module-wlc)。

### 变量

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

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

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

### --version

Print the program version and exit. The [`version`](#cmdoption-wlc-arg-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。覆盖在配置文件中找到的任何值，请参阅 [配置文件](#wlc-config)。该网址应以 `/api/` 结尾，例如 `https://hosted.weblate.org/api/`。

### --key KEY

指定要使用的 API 用户密钥。覆盖在配置文件中找到的任何值，请参阅 [配置文件](#wlc-config)。您可以在 Weblate 的个人资料中找到密钥。当从自动发现的项目配置加载 API URL 时，[`--key`](#cmdoption-wlc-key) 必必须和 [`--url`](#cmdoption-wlc-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`](#cmdoption-wlc-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`](#cmdoption-wlc-url).

### --config PATH

只从 `PATH` 而不是从发现的全局和项目配置文件加载配置，见 [配置文件](#wlc-config)。

### --config-section SECTION

选择要使用的配置文件部分，而不是 `[weblate]` ，见 [配置文件](#wlc-config)。

### 对象路径

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
[配置文件](#wlc-config) when the path is omitted. The [`ls`](#cmdoption-wlc-arg-ls) and
[`download`](#cmdoption-wlc-arg-download) commands also use this setting before falling back to their
no-object behavior. For [`list-components`](#cmdoption-wlc-arg-list-components) and
[`list-translations`](#cmdoption-wlc-arg-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](https://docs.weblate.org/zh-cn/latest/user/search.md).

### 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`](#cmdoption-wlc-output) or to redirected standard output. It refuses to
write raw file content to an interactive terminal.

For a component or project, [`--output`](#cmdoption-wlc-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}

要使用的上传方法，参见 [导入方式](https://docs.weblate.org/zh-cn/latest/user/files.md#upload-method)。默认为 `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

设置额外的字符串标记。

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

<a id="wlc-config"></a>

## 配置文件

当提供了 [`--config`](#cmdoption-wlc-config) 时，**wlc** 只加载那个文件。

没有 [`--config`](#cmdoption-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`](#cmdoption-wlc-config-section) 进行自定义）：

### key

#### Versionremoved
Removed in version 1.17: 用 `[keys]` 部分指定作用域限定为单独 API URL 的 key，见 [旧式设定](#wlc-legacy)。

### 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 文件，例如：

```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]` 部分：

```ini
[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:

```ini
[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.

#### Versionchanged
在 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`](#cmdoption-wlc-config) files are trusted.

In CI, unscoped keys must pin the API URL explicitly: set both
[`WLC_URL`](#envvar-WLC_URL) and [`WLC_KEY`](#envvar-WLC_KEY), or use [`--url`](#cmdoption-wlc-url) together with
[`--key`](#cmdoption-wlc-key).

## 环境变量

#### Versionadded
Added in version 1.18.0.

#### Versionchanged
在 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.

#### Versionchanged
在 2.2.0 版本发生变更: Insecure HTTP and TLS environment overrides require [`WLC_URL`](#envvar-WLC_URL) when
the API URL would otherwise come from automatically discovered project
configuration.

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

### WLC_URL

API 网址

### WLC_KEY

API key. When the API URL would otherwise come from automatically discovered
project configuration, [`WLC_KEY`](#envvar-WLC_KEY) is accepted only together with
[`WLC_URL`](#envvar-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`](#envvar-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`](#envvar-WLC_URL).

The same protection applies to command-line arguments: [`--key`](#cmdoption-wlc-key),
[`--allow-insecure-http`](#cmdoption-wlc-allow-insecure-http), and [`--allow-insecure-ssl`](#cmdoption-wlc-allow-insecure-ssl) are accepted
with automatically discovered project configuration only when [`--url`](#cmdoption-wlc-url)
is provided.

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

1. 命令行参数（[`--url`](#cmdoption-wlc-url)、[`--key`](#cmdoption-wlc-key)）。
2. 环境变量（[`WLC_URL`](#envvar-WLC_URL)、[`WLC_KEY`](#envvar-WLC_KEY)）。
3. 未使用 [`--config`](#cmdoption-wlc-config) 时，从 [`--config`](#cmdoption-wlc-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.

<a id="wlc-security"></a>

## 安全模型

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`](#cmdoption-wlc-config) file when this is not desired.

The command-line client accepts API keys from [`--key`](#cmdoption-wlc-key),
[`WLC_KEY`](#envvar-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](https://github.com/WeblateOrg/wlc/blob/main/THREAT_MODEL.md) 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](https://docs.weblate.org/zh-cn/latest/security/issues.md#security).

## 示例

打印当前程序版本：

```sh
$ wlc version
```

列出所有项目：

```sh
$ 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/
```

上传翻译文件：

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

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

```sh
$ 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/
```

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

```sh
$ wlc commit
```