Weblate 用戶端¶

安裝¶

Weblate 用戶端以獨立套件發行，並包含 Python 模組。原始碼由 WeblateOrg/wlc 儲存庫維護。若要使用下列指令，請透過 pip 安裝 wlc：

pip install wlc

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

uvx wlc --help

提示

您也可以將 wlc 作為 Python 模組使用，請參閱 wlc。

Docker 使用¶

Weblate 用戶端也提供 Docker 映像檔可用。

映像檔發布於 Docker Hub 和 GitHub Container Registry。下列範例使用 Docker Hub 的映像檔名稱。

安裝：

docker pull weblate/wlc

可用的標籤如下：

latest: 最新的穩定版本。
完整版本號，例如 2.2.0: 指定的穩定版本。
主版本號，例如 2: 該主版本系列中的最新穩定版本。
edge: 來自 main 分支的目前開發版本。
edge-YYYY-MM-DD-COMMIT: 指定的開發版本快照。

若要從來源檢出版本建置映像檔：

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

掛載的儲存庫若在專案設定中提供 API URL，而你又將未限定專案範圍的 API 金鑰傳入容器，就必須明確指定 URL：WLC_KEY 必須搭配 WLC_URL，--key 必須搭配 --url。使用 --allow-insecure-http 和 --allow-insecure-ssl 覆寫選項時，也必須使用相同的搭配方式。

若設定的 API URL 使用非本機的 http://，且提供了 API 金鑰，除非明確啟用不安全的 HTTP，否則容器會拒絕傳送金鑰。請優先使用 HTTPS；舊版部署環境可傳入 --allow-insecure-http 或設定 WLC_ALLOW_INSECURE_HTTP。TLS 憑證一律預設驗證，包括迴路位址 URL。只有在無法啟用憑證驗證時，才使用 --allow-insecure-ssl 或 WLC_ALLOW_INSECURE_SSL。

開始使用¶

最容易的開始方式，是在 ~/.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 版的變更: 已不再支援全域 allow_insecure_http 設定。請改在 [insecure_http] 區段設定來源。

移轉舊式設定：

[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 是可透過 Weblate 的 REST API 遠端管理 Weblate 的 Python 函式庫與命令列工具。命令列工具的指令名稱為 wlc；Python API 請參閱 wlc。

引數¶

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

--format {csv,json,text,html}¶: 指定輸出格式。預設為 text。

--version¶: 輸出程式版本資訊後結束。version 指令支援設定輸出格式，也可以只輸出版本號。

--debug¶: 輸出詳細的 HTTP 通訊內容。Authorization 標頭值會遮蔽，要求本文不會記錄，但查詢參數會記錄；請勿在查詢參數中放入機密資訊。

--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 或迴路位址 HTTP；此選項只適用於無法使用 HTTPS 的舊版部署環境。此選項只會在本次執行期間啟用不安全的 HTTP。若 API URL 來自自動探索的專案設定，此選項必須搭配 --url。

--allow-insecure-ssl¶: 在本次執行期間停用 TLS 憑證驗證。所有 HTTPS URL 預設都會驗證憑證，包括迴路位址 URL。若 API URL 來自自動探索的專案設定，此選項必須搭配 --url。

--config PATH¶: 只從 PATH 而不是從發現的全域和專案設定檔案載入設定，見設定檔案。

--config-section SECTION¶: 指定要使用的設定檔區段，以取代 [weblate]；請參閱設定檔案。

物件路徑¶

操作物件的指令可接受下列其中一種路徑：

PROJECT: 專案 slug。
PROJECT/COMPONENT: 組件 slug，包含所屬專案。
PROJECT/COMPONENT/LANGUAGE: 翻譯語言，包含所屬專案與組件。
UNIT_ID: 數值型翻譯單元 ID。只有明確支援單元的指令才接受此格式。

需要物件路徑的指令若未收到路徑，會使用設定檔案中的 translation 設定。ls 和 download 指令也會先使用此設定，再採用不需要物件的行為。list-components 和 list-translations 若未指定物件，一律會列出整個 Weblate 執行個體的項目。

指令¶

以下指令可用：

version¶

列印目前版本。

--bare¶: 只輸出版本號。

list-languages¶: 列出 Weblate 中的所有語言。

list-projects¶: 列出 Weblate 中的所有專案。

list-components¶: 列出 Weblate 中的所有組件，或指定專案中的組件。

list-translations¶: 列出 Weblate 中的所有翻譯，或指定組件中的翻譯。

list-units¶

列出指定翻譯中的所有字串單元。

--query QUERY¶: 使用搜尋查詢語法篩選翻譯單元。

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¶

下載翻譯檔案。下載翻譯時，wlc 會將檔案寫入 --output 指定的位置，或寫至重新導向的標準輸出。若互動式終端機沒有重新導向，程式會拒絕直接輸出原始檔案內容。

下載組件或專案時，必須指定 --output，並將其設為目錄。wlc 會為每個組件寫入一個 ZIP 封存檔。未指定物件時，則會以相同方式下載 Weblate 執行個體中的每個組件。

--convert FORMAT¶: 要求伺服器將內容轉換為 FORMAT。未指定時不會進行轉換。

--output PATH¶: 指定翻譯的輸出檔案，或組件、專案及整個執行個體下載內容的輸出目錄。使用 - 將翻譯寫至標準輸出。

--no-glossary¶: 整個組件、專案或 Weblate 執行個體的下載都不會包含詞彙表組件。

upload¶

上傳翻譯檔案。

--overwrite¶: 覆寫現有的已翻譯字串。這相當於 --conflicts replace-translated。

--conflicts {ignore,replace-translated,replace-approved}¶: 指定遇到現有翻譯衝突時的處理方式。

--input PATH¶: 從 PATH 讀取內容。若未指定或指定為 -，則從標準輸入讀取。

--method {translate,approve,suggest,fuzzy,replace,source,add}¶: 要使用的上傳方式，請參閱匯入方法。預設為 translate。

--fuzzy {process,approve}¶: 指定如何處理 fuzzy 字串（標記為待編輯）。

--author-name NAME¶: 作者名稱，用來覆寫目前已驗證的使用者

--author-email EMAIL¶: 作者電子郵件地址，用來覆寫目前已驗證的使用者

edit-unit¶

更新翻譯單元。必須至少指定一個更新選項。

--target TARGET [TARGET ...]¶: 設定一個或多個譯文。

--state STATE¶: 設定字串狀態：0 代表空白、10 代表 fuzzy、20 代表已翻譯，30 代表已核准。

--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: 放在儲存庫中的專案設定檔案。

專案設定會在全域設定之後載入，並覆寫相符的設定。此檔可以指定 API URL、預設物件、要求設定，以及與 URL 相符的 API 金鑰，讓複製下來的儲存庫能自動選擇 Weblate 伺服器與翻譯。

只載入離得最近的專案設定。忽略較遠父目錄中的設定檔案。

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

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

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

translation: 供接受物件的指令使用的預設物件路徑：專案、組件、翻譯或數值型字串單元 ID。

retries, timeout, allowed_methods, backoff_factor, status_forcelist

HTTP 要求重試與逾時設定。retries 預設為 0，backoff_factor 預設為 0。status_forcelist 是以逗號分隔的 HTTP 狀態碼清單，符合的狀態碼會觸發重試；預設為空。

allowed_methods 會列出可重試的方法，項目以逗號或空白分隔。預設為 HEAD、DELETE、OPTIONS、PUT 和 GET。這些重試設定會傳遞給 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

這可讓你將金鑰儲存在個人設定中，同時使用 VCS 儲存庫中的 .weblate 設定，讓 wlc 知道要連線至哪部伺服器。[keys] 查找會限定於完整的已設定 API URL，而不只是網路來源位址。

專案設定也可以提供或取代 [keys] 中相符的項目。請勿將重要的 API 金鑰提交至版本控制；一般應將金鑰保留在個人設定中，並只在專案設定中放置 API URL 與預設物件。

不安全傳輸的例外設定會儲存在受信任使用者設定中依來源位址範圍區分的區段：

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

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

來源位址（origin）由通訊協定、標準化主機名稱與有效連接埠組成。API 路徑會忽略，不同通訊協定與連接埠則彼此隔離。[insecure_http] 區段允許對相符的來源位址使用非本機 HTTP 傳送 API 金鑰。[insecure_ssl] 區段會停用相符來源位址的 TLS 憑證驗證。

在 2.2.0 版的變更: 所有主機的 TLS 憑證預設都會驗證。不安全的 HTTP 與 TLS 設定會依來源位址區分。自動探索的專案設定不能在這些區段新增項目，也不能啟用已移除的全域設定。使用者設定與明確選取的 --config 檔案都受信任。

在 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 版的變更: 若 API URL 原本會來自自動探索的專案設定，不安全的 HTTP 與 TLS 環境覆寫就必須搭配 WLC_URL。

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 或迴路位址 HTTP。0 或 false 等其他值會視為未設定。若 API URL 原本會來自自動探索的專案設定，只有搭配 WLC_URL 才會接受此變數。

WLC_ALLOW_INSECURE_SSL¶: 設為 1、true、yes 或 on，即可停用 TLS 憑證驗證。0 或 false 等其他值會視為未設定。若 API URL 原本會來自自動探索的專案設定，只有搭配 WLC_URL 才會接受此變數。

相同的防護也適用於命令列引數：使用自動探索的專案設定時，只有提供 --url 才會接受 --key、--allow-insecure-http 和 --allow-insecure-ssl。

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

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

不安全傳輸的啟用選項只會開啟例外，不會像一般設定一樣依優先順序覆寫。你可以透過命令列或環境變數覆寫啟用，也可以在受信任的 [insecure_http] 或 [insecure_ssl] 區段設定相符的來源位址。自動探索的專案設定不能新增受信任的來源位址。

安全性模型¶

專案設定屬於儲存庫工作流程的一部分，並刻意授權其指定 API 端點、預設物件、要求設定及與 URL 相符的 API 金鑰。在儲存庫中執行 wlc，即表示授權最近的專案設定指定接收指令與上傳資料的伺服器，也授權該伺服器提供要顯示或下載的內容。若不希望如此，請使用明確指定且受信任的 --config 檔案。

命令列用戶端可以從 --key、WLC_KEY 或 [keys] 區段取得 API 金鑰。它不會從 .netrc 或 NETRC 指定的檔案載入 HTTP 認證。API URL 中若內嵌憑證，就會遭到拒絕；請改用 API 金鑰。其他 Requests 環境整合功能（包括 Proxy 與 CA 憑證套件變數）仍會啟用。

wlc 威脅模型說明完整的信任邊界、安全屬性、非目標事項及下游責任。與版本相符的副本也包含在原始碼與 wheel 發行套件中。請依照 Weblate 弱點回報流程回報安全問題。

範例¶

列印目前程式版本：

$ 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