Weblate 用戶端

安裝

The Weblate Client is shipped separately and includes the Python module. To use the commands below, you need to install wlc using pip:

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

You might want to pass your 配置檔案 to the Docker container. When your repository contains a project configuration such as .weblate, the easiest approach is to add your current directory as the /home/weblate volume:

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 easiest way to get started is to create a personal wlc configuration in ~/.config/weblate (see 配置檔案 for the full discovery rules and other locations):

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

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

然後您可以在預設伺服器上呼叫指令：

wlc ls
wlc commit sandbox/hello-world

也參考

配置檔案

舊式配置

在 1.17 版的變更: The legacy configuration using unscoped key is no longer supported.

遷移舊式配置：

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

To a configuration with key scoped to an API URL:

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

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

概要

wlc [arguments] <command> [options]

Commands actually indicate which operation should be performed.

描述

Weblate Client is a Python library and command-line utility to manage Weblate remotely using Weblate 的 REST API. The command-line utility can be invoked as wlc and is built-in on wlc.

引數

程式接受以下參數來定義輸出格式或使用哪個Weblate實例。這些參數必須位於任何指令之前。

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

指定輸出格式。

--url URL

指定 API URL。覆寫在配置檔案中找到的任何值，請參閱 配置檔案。該 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

Load configuration only from PATH instead of the discovered global and project configuration files, see 配置檔案.

--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

Upload method to use, see 匯入方法.

--fuzzy

Fuzzy (marked for edit) strings processing (empty, process, approve)

--author-name

Author name, to override currently authenticated user

--author-email

Author e-mail, to override currently authenticated user

提示

You can get more detailed information on invoking individual commands by passing --help, for example: wlc ls --help.

配置檔案

When --config is provided, wlc loads only that file.

Without --config, wlc first loads the discovered global configuration file from the standard platform-specific locations:

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

Global configuration file on Windows in the roamed profile.

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

Global configuration file on Windows in the local profile.

~/.config/weblate

類 Unix 系統上的全域配置檔案。

/etc/xdg/weblate

系統範圍回退配置檔案。

此程式遵循 XDG 規範，所以您可以透過 XDG_CONFIG_HOME 或 XDG_CONFIG_DIRS 環境變數調整配置檔案的擺放位置。

On Windows APPDATA and LOCALAPPDATA directories are the preferred locations for the configuration file.

After loading the global configuration, wlc loads the nearest project configuration file from the current directory or its parents:

.weblate 、 .weblate.ini 、 weblate.ini

放在儲存庫中的專案配置檔案。

Only the closest project configuration file is loaded. Configuration files in farther parent directories are ignored.

可以在 [weblate] 部分中配置以下設定（您可以通過 --config-section 進行自訂）：

key

在 1.17 版被移除: Use the [keys] section to specify keys scoped for individual API URLs, see 舊式配置.

url

API 伺服器 URL，預設為 http://127.0.0.1:8000/api/。

translation

Path to the default translation - component or project.

retries, timeout, allowed_methods, backoff_factor, status_forcelist

Optional HTTP retry and timeout settings passed to urllib3. Use allowed_methods to list the request methods that may be retried. Current wlc releases use this setting name in place of the older method_whitelist option.

配置檔案是個 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.

環境變數

在 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 URL

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.

The configuration precedence (highest to lowest) is:

1. 命令列引數 （--url、--key）。

2. 環境變數 （WLC_URL、WLC_KEY）。

3. Configuration loaded from --config, or from the discovered global configuration plus the nearest project configuration when --config is not used.

範例

列印當前程式版本：

$ 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

You can also designate what project wlc should work on:

$ 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