Weblate 用戶端

安裝

The Weblate Client is shipped separately and includes the Python module. The source code is maintained in the WeblateOrg/wlc repository. 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 映像檔可用。

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

安裝：

docker pull weblate/wlc

The following tags are available:

latest

Latest stable release.

Full version, for example 2.2.0

A specific stable release.

Major version, for example 2

Latest stable release in that major series.

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 .

Docker 容器會使用 Weblate Client 預設值，並連線至部署在 localhost 的 API。請使用一般的 wlc 引數或環境變數設定 API URL 及 API 金鑰，例如 --url、--key、WLC_URL 及 WLC_KEY。預設會拒絕透過非本機 http:// URL 傳送 API 金鑰；請使用 HTTPS、本機開發用的 Loopback HTTP，或明確選擇允許不安全的 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 Client is a Python library and command-line utility to manage Weblate remotely using Weblate 的 REST API. Invoke the command-line utility as wlc; see wlc for the Python API.

引數

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

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

Specify the output format. The default is 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。覆寫在設定檔案中找到的任何值，請參閱 設定檔案。該 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

Selects the configuration file section to use instead of [weblate], see 設定檔案.

Object paths

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

PROJECT

Project slug.

PROJECT/COMPONENT

Component slug, including its project.

PROJECT/COMPONENT/LANGUAGE

Translation language, including its project and component.

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

Prints only the version number.

list-languages

Lists all languages in Weblate.

list-projects

Lists all projects in Weblate.

list-components

Lists all components in Weblate, or components in the specified project.

list-translations

Lists all translations in Weblate, or translations in the specified component.

list-units

Lists units in the specified translation.

--query QUERY

Filters units using the search query syntax.

show

Shows a project, component, translation, or unit.

delete

Deletes a project, component, translation, or unit without a confirmation prompt.

ls

Lists all projects when no object is specified, components in a project, or translations in a component.

commit

提交在 Weblate 物件（翻譯，組件或專案）中所做的變更。

pull

拉取遠端儲存庫的變更到 Weblate 對像中（翻譯，組件或專案）。

push

將 Weblate 物件變更推送到遠端儲存庫（翻譯，組件或專案）。

reset

重設 Weblate 物件中的變更以比對遠端儲存庫（翻譯、組件或專案）。

cleanup

刪除 Weblate 對像中所有未追蹤的變更以相符遠端儲存庫（翻譯，組件或專案）。

repo

顯示給定 Weblate 物件（翻譯，組件或專案）的儲存庫狀態。

stats

顯示給定 Weblate 物件（翻譯，組件或專案）的詳細統計資料。

lock-status

Displays the lock status of a component.

lock

鎖定組件以防止在 Weblate 中進一步翻譯。

unlock

解鎖 Weblate 組件的翻譯。

changes

Displays changes for a project, component, or translation.

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}

Selects how conflicts with existing translations are handled.

--input PATH

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

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

Upload method to use, see 匯入方法. The default is translate.

--fuzzy {process,approve}

Selects processing of fuzzy strings (marked for edit).

--author-name NAME

作者名稱，用來覆寫目前已驗證的使用者

--author-email EMAIL

作者電子郵件地址，用來覆寫目前已驗證的使用者

edit-unit

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

--target TARGET [TARGET ...]

Sets one or more translated strings.

--state STATE

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

--explanation EXPLANATION

Sets the string explanation.

--extra-flags FLAGS

Sets additional string 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

Alternative global configuration filename on Unix-like systems.

/etc/xdg/weblate

系統範圍回退設定檔案。

/etc/xdg/weblate.ini

Alternative system-wide fallback filename.

此程式遵循 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

在 1.17 版被移除: 用 [keys] 部分指定範圍限定為單獨 API URL 的 key，見 舊式設定。

url

API 伺服器 URL，預設為 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 is the request timeout in seconds and defaults to 300. Current wlc releases use allowed_methods 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 complete configured API URL, not merely its network origin.

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.

在 CI 中，未限定範圍的金鑰必須明確固定 API URL：同時設定 WLC_URL 及 WLC_KEY，或將 --url 與 --key 搭配使用。

環境變數

在 1.18.0 版被加入.

在 2.0.1 版的變更: 自動探索專案設定時，未限定範圍的 API 金鑰需要明確指定 API URL。除非明確啟用不安全的 HTTP，否則會拒絕透過非本機 http:// URL 傳送 API 金鑰。

在 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 則以機密資料注入：

WLC_URL

API URL

WLC_KEY

API 金鑰。若 API URL 原本會來自自動探索的專案設定，只有同時提供 WLC_URL 時，才會接受 WLC_KEY。預設會拒絕透過非本機 http:// URL 傳送 API 金鑰。

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 及金鑰的設定優先順序如下（由高至低）：

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