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

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

當掛載的儲存庫在專案設定中提供 API URL，而您將未限定範圍的 API 金鑰傳入容器時，也必須明確固定 URL：WLC_KEY 需要搭配 WLC_URL，--key 則需要搭配 --url。

若已設定的 API URL 使用非本機 http://，且提供了 API 金鑰，除非明確啟用不安全的 HTTP，否則容器會拒絕傳送金鑰。請優先使用 HTTPS；舊版部署環境可傳入 --allow-insecure-http 或設定 WLC_ALLOW_INSECURE_HTTP。

開始使用¶

最容易的開始方式，是在 ~/.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。覆寫在設定檔案中找到的任何值，請參閱設定檔案。該 URL 應以 /api/ 結尾，例如 https://hosted.weblate.org/api/。

--key KEY¶: 指定要使用的 API 使用者金鑰。這會覆寫設定檔中的任何值；請參閱設定檔案。您可在 Weblate 的個人資料中找到金鑰。API URL 從自動探查的專案設定載入時，--key 必須與 --url 一併使用。預設會拒絕透過非本機 http:// URL 傳送 API 金鑰。

--allow-insecure-http¶: 允許透過非本機 http:// URL 傳送 API 金鑰。請優先改用 HTTPS 或 Loopback HTTP；此選項僅供無法使用 HTTPS 的舊版部署環境使用。此選項只會為目前這次執行啟用不安全的 HTTP；省略此選項不會停用設定中的 allow_insecure_http。

--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: 在 1.17 版被移除: 用 [keys] 部分指定範圍限定為單獨 API URL 的 key，見舊式設定。

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

translation: 預設翻譯的路徑 —— 元件或專案。

allow_insecure_http: 允許 API 金鑰透過非本機 http:// URL 傳送，預設為 false。如 http://127.0.0.1:8000/api/ 的迴路 HTTP URL 仍可用於本機開發，不需啟用此選項。請優先使用 HTTPS，不要啟用此設定。自動探查的專案設定檔無法啟用此選項；請在使用者設定、明確指定的 --config 檔案、WLC_ALLOW_INSECURE_HTTP 或 --allow-insecure-http 中設定。此設定具有累加性：任一可信任來源啟用不安全 HTTP 即為足夠，指令列或環境變數來源中的 false 或未設定值不會將其停用。

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
allow_insecure_http = false

API 金鑰儲存在 [keys] 部分中：

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

這樣，您就可以在版本控制系統儲存庫中使用 .weblate 設定時，將金鑰儲存在個人設定中，以便 wlc 知道它應該與哪個伺服器通訊。[keys] 查詢範圍限定於精確的 API URL。

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

環境變數¶

在 1.18.0 版被加入.

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

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¶: 設為 1、true、yes 或 on，即可允許透過非本機 http:// URL 傳送 API 金鑰。請優先改用 HTTPS 或 Loopback HTTP。0 或 false 等其他值會視為未設定，且不會停用設定中的 allow_insecure_http。

同一項保護也適用於指令列引數：自動探索專案設定時，只有提供 --url 才會接受 --key。

API URL 及金鑰的設定優先順序如下（由高至低）：

指令列引數（--url、--key）。
環境變數（WLC_URL、WLC_KEY）。
從 --config 載入的設定；未使用 --config 時，則為探查到的全域設定及最接近的專案設定。

選擇允許不安全 HTTP 的設定只能用來啟用功能，並非一般的優先順序設定。傳入 --allow-insecure-http、WLC_ALLOW_INSECURE_HTTP 為 true 值，或受信任設定中的 allow_insecure_http 已啟用時，便會啟用此功能。自動探索的專案設定無法啟用此功能；請改在使用者設定中設定，或傳入明確指定的 --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