開始為 Weblate 貢獻程式碼

要理解 Weblate 原始碼，請瀏覽 Weblate 原始碼、 Weblate 前端 和 Weblate 內部。

從程式碼庫開始

若要熟悉 Weblate 程式碼庫，可以先嘗試處理標有 good first issue 的問題。

歡迎直接開始處理這些問題，不必事先詢問。只要在問題中留言告知，讓大家知道已有人著手處理即可。

本機執行 Weblate

開始參與 Weblate 開發最方便的方式，是依照 從原始碼中安裝 操作。這會建立含可編輯 Weblate 原始碼的 Python 環境。

1. 複製 Weblate 原始碼：

   git clone https://github.com/WeblateOrg/weblate.git
   cd weblate
   

2. 安裝 Weblate 和所有對開發有用的相依套件：

   uv sync --all-extras --dev
   

3. 啟動開發伺服器：

   uv run weblate runserver
   

4. 取決於設定，您也許想啟動 Celery workers：

   uv run ./weblate/examples/celery start
   

5. 若要執行測試（更多細節請參閱 Weblate 的本機測試）：

   . scripts/test-database.sh
   uv run pytest
   

也參考

從原始碼中安裝

用於測試和 lint 的開發容器

開發容器會準備 Python 相依套件、PostgreSQL、Valkey、編譯後的翻譯檔和靜態檔案，以供執行測試和 lint 檢查。一般複本和連結的 Git 工作樹都適用。每個結帳目錄各自擁有容器、網路、資料庫、虛擬環境及快取；在預設測試設定檔中不會發布主機連接埠。選用的應用程式設定檔會執行 Weblate 和工作程序，供本機 QA 使用，並使用獨立儲存空間及動態配置的 localhost 連接埠。

請在主機上安裝含 Compose 外掛程式的 Docker、Git，以及 Python 3.12 或更新版本。若要使用命令列工作流程，也請安裝 Node.js 20 或更新版本及 Dev Container CLI：

npm install --global @devcontainers/cli@0.89.0
./scripts/devcontainer up
./scripts/devcontainer doctor
./scripts/devcontainer exec -- uv run pytest weblate/lang/tests.py
./scripts/devcontainer exec -- uv run prek run --all-files

也可以在 Visual Studio Code 中開啟結帳目錄，安裝 Dev Containers 擴充功能，並選擇 Dev Containers: Reopen in Container。兩種工作流程都會使用 .devcontainer/devcontainer.json，並等待初始設定完成。若使用 scripts/devcontainer 的預設後端，必須另外安裝 CLI。若要不使用 Node.js 或 Dev Container CLI，直接透過 Docker Compose 執行，請在指令前加上 --backend compose：

./scripts/devcontainer --backend compose up
./scripts/devcontainer --backend compose exec -- uv run pytest weblate/lang/tests.py

同一結帳目錄的兩種後端會共用相同的測試環境。Compose 後端每次執行 up 都會進行初始設定。CI 會在 ARM Linux 執行器上檢查兩種後端，也會在不同工作樹中同時執行應用程式 QA。

初始設定會使用已凍結的相依套件鎖定檔，並從原始碼建置 lxml 和 xmlsec，與 CI 的方式相同。初次設定需要網路連線，才能下載映像和相依套件；lint 掛鉤第一次使用時也會下載執行環境。變更相依套件後，請重新執行：

./scripts/devcontainer bootstrap

Pytest 首次執行時會建立並遷移測試資料庫，之後則重複使用。若遷移變更不相容而需要重建資料庫，請對 pytest 加上 --create-db。容器不會使用主機上現有的虛擬環境或本機 weblate/settings.py。

若要處理個別工作，請建立工作樹並啟動其環境：

git worktree add ../weblate-task -b task/example
cd ../weblate-task
./scripts/devcontainer up

環境識別碼取自結帳目錄的絕對路徑，因此切換分支時會保留原環境。移動或刪除結帳目錄前，請先停止或刪除環境。連結的工作樹也會在原始路徑掛載共用 Git 中繼資料目錄，因此其中的 Git 操作會影響與主機 Git 操作相同的儲存庫。其他工作樹的來源檔不會掛載。使用此工作流程時，請取消設定 COMPOSE_PROJECT_NAME，並從結帳目錄、.devcontainer 及啟動工具的目錄中的 .env 檔移除相關設定。初始化程序會拒絕這些設定，因為它們可能覆寫結帳目錄專屬的專案名稱。

若要停止容器並保留資料，或明確刪除容器及磁碟區：

./scripts/devcontainer stop
./scripts/devcontainer destroy --yes

這些指令只會管理目前結帳目錄的測試環境，不會移除來源檔案或由 rundev.sh 啟動的應用程式環境。透過 ./rundev.sh test 執行的測試會共用此測試環境，因此停止環境會同時影響這兩種測試啟動方式。關閉 IDE 會停止此結帳目錄的整個 Compose 專案（包括應用程式 QA），但會保留資料。啟動器的停止指令只會影響所選設定檔。請在 stop、logs 或 destroy 前加上 --all，以管理此結帳目錄中的兩種設定檔。

如果初始設定失敗，請使用 ./scripts/devcontainer doctor 檢查來源路徑、服務連線、相依套件一致性及測試素材。服務就緒檢查設有逾時。容器會保留供檢查，其記錄可透過 docker compose 讀取：

docker compose -f .devcontainer/compose.yaml -f .devcontainer/compose.local.json logs

產生的 .devcontainer/compose.local.json 會由 Git 忽略，並包含結帳目錄專屬路徑。請勿在此檔案中放入認證資訊或主機設定。

共用開發映像在 ARM 和 amd64 上都會從 XtraDeb Ubuntu 儲存庫安裝 Chromium 及相符的驅動程式。這些系統套件沒有固定版本。若要取得瀏覽器更新，請停用 Docker 建置快取進行建置，並重建測試容器：

./scripts/devcontainer --backend compose compose -- build --no-cache developer
./scripts/devcontainer --backend compose restart

若要確認瀏覽器能否啟動、載入頁面及執行 JavaScript，或在必須有瀏覽器的情況下執行現有 Selenium 測試套件：

./scripts/devcontainer doctor --browser
./scripts/devcontainer browser-test
./rundev.sh browser-test -k test_login_form_accessibility
./rundev.sh browser-test --target weblate/trans/tests/test_selenium.py::SeleniumTests::test_js_unit_tests

browser-test 會準備隔離的測試環境、執行瀏覽器診斷，並設定 CI_SELENIUM=1，讓 WebDriver 無法使用時測試失敗，而非略過。它會輸出 pytest 的測試總數和略過原因，保留合理的略過項目及 pytest 的結束狀態。其他引數會傳給 pytest；重複使用 --target 可選擇特定測試路徑或節點 ID，取代預設的 Selenium 模組。doctor --browser 會透過任一啟動器檢查測試設定檔，並回報已安裝的瀏覽器和驅動程式版本。

映像會將 WEBLATE_TEST_CHROME_BINARY 和 WEBLATE_TEST_CHROMEDRIVER 設為已安裝的執行檔路徑。這些僅供開發使用的變數會供診斷和 Selenium 測試共用，避免自動下載瀏覽器。若在映像外執行時不設定這些變數，Selenium 會維持預設的瀏覽器探索方式。若要進行探索式 QA，請使用自己的瀏覽器開啟應用程式設定檔的 URL。

主要目標是 Linux 和 WSL2，且工作目錄位於 Linux 檔案系統。macOS Docker Desktop 和 Codespaces 使用相同設定，但不在 Linux CI 冒煙測試的涵蓋範圍內。主機路徑掛載不支援原生 Windows 路徑和遠端 Docker daemon。

在 Docker 中本機執行 Weblate

請在主機上安裝含 Compose 外掛程式的 Docker、Git，以及 Python 3.12 或更新版本。使用以下指令啟動開發應用程式：

./rundev.sh

這與 ./scripts/devcontainer --profile app up 相同。兩個指令都會使用與測試環境相同的啟動器和 Compose 專案；應用程式設定檔不需要 Node.js 或 Dev Container CLI。

啟動器會建置開發映像，透過 supervisor 啟動 Weblate、網頁工作程序和 Celery 工作程序，並在 Weblate 就緒時顯示應用程式及 Maildev 郵件信箱的 URL。請使用帳號 admin 和密碼 admin 登入。安裝完成時沒有任何資料，請接著參閱 新增專案。

Docker 會指派綁定至 127.0.0.1 的可用 HTTP 連接埠。每個工作樹都各自擁有應用程式資料庫、Valkey 執行個體、資料、虛擬環境、家目錄和快取，且與測試設定檔分開。SMTP、PostgreSQL 和 Valkey 的連接埠不會發布至主機。Weblate 會使用探索到的應用程式 URL 產生連結並設定驗證來源。若要再次顯示目前 URL：

./rundev.sh urls
./rundev.sh urls --json

若要透過完整的應用程式操作流程實際使用背景工作程序：

./rundev.sh application-test

也可使用 ./scripts/devcontainer application-test 執行。這會啟動應用程式設定檔，並使用管理員 API 權杖匯入小型組件封存檔、儲存翻譯、要求執行背景提交，再檢查已提交的 Git 檔案。接著檢查匯出的 ZIP、API 和轉譯後應用程式頁面中的最終翻譯統計資料、翻譯記憶，以及 Maildev 收到的翻譯通知。匯出檔案會同步產生，其內容必須反映已完成的背景工作。

另一項交易檢查會在測試資料列提交前，先將實際工作排入佇列、等待重試，再確認資料列提交後工作會成功重新傳送。此測試套件需要使用非 eager 模式的 Celery、應用程式的 Valkey broker，以及 Maildev。輪詢設有期限，工作程序任務失敗時會附上追蹤資訊，測試失敗時會輸出應用程式服務記錄。CI 會在 Docker 開發工作中，以及同時運作的隔離工作樹中執行這些操作流程。

每次執行都會建立名稱唯一的 celery-qa- 專案和通知收件者，並為其設定無法使用的密碼。這些測試資料會保留供檢查，包括測試失敗後也一樣；此測試套件不會重設現有資料。完成後，請透過應用程式移除這些專案和使用者，或對可丟棄的應用程式環境執行 destroy --yes。

重新建立或重新啟動容器後，連接埠可能會變更。請使用 ./rundev.sh restart 重新啟動並重新探索連接埠；直接重新啟動 Docker 無法初始化應用程式網域。一般啟動會重用未變更的容器。Docker 重新啟動後，應用程式容器不會自動重新啟動。映像的 Python 次要版本變更時，啟動流程會重建應用程式虛擬環境並重新安裝相依套件。應用程式資料會保留。

若要從應用程式容器內存取應用程式資料庫：

./rundev.sh exec -- weblate dbshell

應用程式服務定義位於 dev-docker/docker-compose.yml，並納入共用 Compose 設定。請使用啟動器初始化路徑和連接埠。若要執行其他 Compose 操作，請使用 ./rundev.sh compose -- COMMAND（或現有捷徑，例如 ./rundev.sh ps）。全專案的 Compose 指令可能同時影響兩種設定檔。

現有的開發環境不會自動遷移。從舊版啟動器更新前，請使用其 ./rundev.sh stop 指令停止容器。若已完成更新，請使用 docker ps 找出舊容器並明確停止。新版啟動器會保留舊環境的資料庫、磁碟區和 dev-docker/data/，但會以全新的應用程式資料啟動。

若要執行測試，請使用 test 參數執行指令碼，並附上 pytest 引數；例如，只執行 weblate.machine 模組中的測試：

./rundev.sh test --exitfirst weblate/machine

此指令會透過 Docker Compose 自動啟動並初始化 開發容器，不需要 Dev Container CLI。測試環境獨立於應用程式及工作程序，並使用不同的資料庫、虛擬環境和快取。每次執行 pytest 前，都會更新相依套件和測試素材。

若要顯示應用程式記錄：

./rundev.sh logs

若要只停止應用程式設定檔並保留資料：

./rundev.sh stop

使用 ./scripts/devcontainer stop 只停止測試環境。若要停止或刪除兩種設定檔（刪除時也會移除磁碟區）：

./rundev.sh --all stop
./rundev.sh --all destroy --yes

若未加上 --all，destroy --yes 只會移除所選設定檔的容器和磁碟區。其他工作樹會繼續執行。

警告

此容器不適合正式環境使用。為簡化開發工作，其安全性有所取捨。

引導您的開發執行個體

您可以使用 import_demo 建立示範翻譯，並使用 createadmin 建立管理員使用者。

若也安裝了 帳務，可以使用 billing_demo 建立示範帳務專案。

使用 PyCharm 為 Weblate 編寫程式碼

PyCharm 是 Python 的著名 IDE，這裡有一些幫助您在其中建立您的 Weblate 專案的指導原則。

考慮到您剛剛將 GitHub 儲存庫複製到一個資料夾中，只需使用 PyCharm 開啟它。一旦 IDE 開啟，第一步要做的是指定您想要使用的直譯器：

選取由 uv sync --all-extras --dev 建立的 .venv 環境，以符合指令列開發環境的設定。您也可以讓 PyCharm 建立 Python 環境，但建議優先使用 uv 管理的環境：

設定直譯器後，別忘了安裝相依套件。使用建議的 uv 管理環境時，請從主控台執行 uv sync --all-extras --dev。

第二步是設定正確的資訊來在 PyCharm 中原生使用 Django：理念是能夠立刻觸發 IDE 中的單元測試。為此，您需要指定該 Django 專案的根路徑及其設定路徑：

請注意，Django project root 是儲存庫的實際根目錄，而不是 Weblate 子目錄。關於設定，您可以使用儲存庫中的 weblate/settings_test.py，您也可以建立自己的設定並將其設定在那裡。

最後一步是執行伺服器，並將中斷點放置在代碼中而能夠除錯它。這通過新增新的 Django Server 設定來完成：

提示

小心被稱為 No reload 的屬性：如果您修改檔案，它會阻止伺服器被實時重新載入。這允許保留現有的除錯器中斷點，而它們通常會在重新載入伺服器時被丟棄。