Weblate에 코드 기여 시작하기¶
Weblate 소스 코드, Weblate 프런트엔드 및 Weblate 내부 구조 를 살펴봄으로써 Weblate 소스 코드를 이해합니다.
코드베이스 시작하기¶
good first issue 로 라벨이 지정된 버그에 도전하여 Weblate 코드베이스에 익숙해지세요.
이러한 이슈에 대해 묻지 않고 바로 작업을 시작할 수 있습니다. 이슈에 작업 시작을 알리기만 하면 누군가가 해당 이슈를 작업 중인 것이 명확해집니다.
Weblate를 로컬에서 실행¶
Weblate 개발을 시작하는 가장 편안한 방법은 소스에서 설치 를 따르는 것입니다. 편집 가능한 Weblate 소스가 있는 Python 환경을 얻을 수 있습니다.
Weblate 소스 코드 복제:
git clone https://github.com/WeblateOrg/weblate.git cd weblate
개발에 유용한 모든 의존성과 함께 Weblate를 설치하세요:
uv sync --all-extras --dev
개발 서버 시작:
uv run weblate runserver
구성에 따라 Celery 워커를 시작할 수도 있음:
uv run ./weblate/examples/celery start
테스트 실행(Weblate 로컬 테스트 에서 자세한 내용 참조):
. scripts/test-database.sh uv run pytest
더 보기
Development container for tests and lint¶
The development container prepares Python dependencies, PostgreSQL, Valkey, compiled translations, and static files for running tests and lint checks. It supports ordinary clones and linked Git worktrees. Each checkout has its own containers, network, database, virtual environment, and caches, with no published host ports in the default test profile. The optional application profile runs Weblate and workers for local QA with separate storage and dynamically allocated localhost ports.
Install Docker with the Compose plugin, Git, and Python 3.12 or newer on the host. For the command-line workflow, also install Node.js 20 or newer and the 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
Alternatively, open the checkout in Visual Studio Code with its Dev Containers
extension and select Dev Containers: Reopen in Container. Both
workflows use .devcontainer/devcontainer.json and wait for bootstrap
to finish. The CLI must be installed separately for the default backend of
scripts/devcontainer. To use Docker Compose directly without Node.js or
the Dev Container CLI, pass --backend compose before the command:
./scripts/devcontainer --backend compose up
./scripts/devcontainer --backend compose exec -- uv run pytest weblate/lang/tests.py
Both backends share the same test environment for a checkout. The Compose
backend runs bootstrap on each up invocation. CI checks both backends on
ARM Linux runners, including concurrent application QA in separate worktrees.
Bootstrap uses the frozen dependency lock and builds lxml and xmlsec
from source, matching CI. Initial setup requires network access to download
images and dependencies; lint hooks download their environments on first use.
After changing dependencies, rerun:
./scripts/devcontainer bootstrap
Pytest creates and migrates its test database on first use and reuses it on
subsequent runs. To recreate it after incompatible migration changes, pass
--create-db to pytest. Existing host virtual environments and local
weblate/settings.py are not used by the container.
For a separate task, create a worktree and start its environment:
git worktree add ../weblate-task -b task/example
cd ../weblate-task
./scripts/devcontainer up
The environment identifier is derived from the checkout’s absolute path,
so changing branches preserves the environment. Stop or destroy the environment
before moving or deleting its checkout. Linked worktrees also mount the shared
Git metadata directory at its original path; Git operations therefore affect
the same repository as host Git operations. Other worktrees’ sources are not
mounted. Unset COMPOSE_PROJECT_NAME when using this workflow, and remove
its assignments from .env files in the checkout, .devcontainer,
and the directory from which you launch the tools. Initialization rejects
these assignments because they can override the checkout-specific project name.
To stop containers while retaining their data, or explicitly delete their containers and volumes:
./scripts/devcontainer stop
./scripts/devcontainer destroy --yes
These commands only manage the current checkout’s test environment. They do
not remove its source files or the application environment started by
rundev.sh. Tests run through ./rundev.sh test share this test
environment, so stopping it affects both test launchers. Closing the IDE stops
the entire checkout’s Compose project, including application QA, while retaining
its data. Launcher stop commands affect only their selected profile. Use
--all before stop, logs, or destroy to manage both profiles in the
checkout.
If setup fails, use ./scripts/devcontainer doctor to inspect the source
paths, service connections, dependency consistency, and test assets. Service
readiness checks have a timeout. Containers remain available for inspection;
their logs can be read with docker compose:
docker compose -f .devcontainer/compose.yaml -f .devcontainer/compose.local.json logs
The generated .devcontainer/compose.local.json is ignored by Git and
contains checkout-specific paths. Keep credentials and host configuration out
of this file.
The shared development image includes native Chromium and its matching driver from the XtraDeb Ubuntu repository on ARM and amd64. These system packages are not version-pinned. To fetch browser updates, rebuild without the Docker build cache and recreate the test container:
./scripts/devcontainer --backend compose compose -- build --no-cache developer
./scripts/devcontainer --backend compose restart
To verify browser startup, page loading, and JavaScript execution, or run the existing Selenium suite with a required browser:
./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 prepares the isolated test environment, runs browser diagnostics,
and sets CI_SELENIUM=1 so unavailable WebDriver fails instead of skipping.
It prints pytest’s test totals and skip reasons, preserving legitimate skips and
pytest’s exit status. Additional arguments are passed to pytest; repeat
--target to select specific test paths or node IDs instead of the default
Selenium module. doctor --browser checks the test profile through either
launcher and reports installed browser and driver versions.
The image sets WEBLATE_TEST_CHROME_BINARY and WEBLATE_TEST_CHROMEDRIVER
to the installed executable paths. These developer-only variables are shared by
the diagnostic and Selenium tests, avoiding automatic browser downloads. Outside
the image, leaving them unset preserves Selenium’s default browser discovery.
Use your own browser with the application profile’s URL for exploratory QA.
Linux and WSL2 with a checkout in the Linux filesystem are the primary targets. macOS Docker Desktop and Codespaces use the same configuration, but are not covered by the Linux CI smoke test. Native Windows paths and remote Docker daemons are not supported by the host-path mounts.
Docker에서 Weblate를 로컬로 실행¶
Install Docker with the Compose plugin, Git, and Python 3.12 or newer on the host. Start the development application with:
./rundev.sh
This is equivalent to ./scripts/devcontainer --profile app up. Both commands
use the same launcher and Compose project as the test environment, without
requiring Node.js or the Dev Container CLI for the application profile.
The launcher builds the development image, starts Weblate with supervised web
and Celery workers, and prints the application and Maildev mailbox URLs when
Weblate is ready. Sign in as admin with password admin. The installation
starts empty; continue with 번역 프로젝트 및 구성요소 추가.
Docker assigns free HTTP ports bound to 127.0.0.1. Each worktree has its own
application database, Valkey instance, data, virtual environment, home, and
caches, separate from the test profile. SMTP, PostgreSQL, and Valkey ports are
not published. Weblate uses the discovered application URL for generated links
and authentication origins. To display the current URLs again:
./rundev.sh urls
./rundev.sh urls --json
To exercise real background workers through complete application journeys:
./rundev.sh application-test
This is also available as ./scripts/devcontainer application-test. It starts
the application profile and uses its administrator API token to import a small
component archive, save a translation, request a background commit, and inspect
the committed Git file. It then checks the exported ZIP, eventual translation
statistics in the API and rendered application page, translation memory, and a
translation notification delivered to
Maildev. Export generation itself is synchronous; its contents must reflect the
completed background work.
A separate transaction check queues a real task before its fixture row is committed, waits for a retry, and verifies successful redelivery after commit. The suite requires non-eager Celery and the application’s Valkey broker and Maildev. Polls have deadlines, worker task failures include their tracebacks, and failures print the application service logs. CI runs these journeys in both the Docker development job and concurrent isolated worktrees.
Each invocation creates a uniquely named celery-qa- project and notification
recipient with an unusable password. These fixtures remain available for
inspection, including after failure; the suite does not reset existing data.
Remove these projects and users through the application when finished, or
destroy --yes the disposable application environment.
Ports can change after containers are recreated or restarted. Use
./rundev.sh restart to restart and rediscover them; direct Docker restarts
cannot initialize the application domain. Ordinary startup reuses unchanged
containers. Application containers do not restart automatically after Docker
restarts. When the image changes Python minor versions, startup recreates the
application virtual environment and reinstalls dependencies. Application data
is retained.
To access the application database from inside its container:
./rundev.sh exec -- weblate dbshell
The application service definitions are in dev-docker/docker-compose.yml
and are included by the shared Compose configuration. Use the launchers to
initialize paths and ports. For other Compose operations, use
./rundev.sh compose -- COMMAND (or existing shortcuts such as
./rundev.sh ps). Project-wide Compose commands can affect both profiles.
Existing development environments are not migrated automatically. Before
updating from the old launcher, stop its containers with its ./rundev.sh stop
command. If already updated, identify the old containers using docker ps
and stop them explicitly. The new launcher leaves their databases, volumes,
and dev-docker/data/ untouched and starts with fresh application data.
To execute tests, run the script with the test parameter and pytest arguments,
for example running only tests in the weblate.machine module:
./rundev.sh test --exitfirst weblate/machine
The command automatically starts and bootstraps the development container using Docker Compose, without requiring the Dev Container CLI. It runs independently of the application and workers, with separate databases, virtual environments, and caches. Each invocation refreshes dependencies and test assets before running pytest.
To display application logs:
./rundev.sh logs
To stop only the application profile, retaining its data:
./rundev.sh stop
Use ./scripts/devcontainer stop to stop only tests. To stop or destroy both
profiles, including their volumes when destroying:
./rundev.sh --all stop
./rundev.sh --all destroy --yes
Without --all, destroy --yes removes only the selected profile’s
containers and volumes. Other worktrees remain running.
경고
이 컨테이너는 프로덕션 사용에 적합하지 않습니다. 개발을 쉽게 하기 위해 보안이 희생됩니다.
개발 인스턴스 부트스트랩¶
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 속성에 주의하세요. 파일을 수정할 때 서버가 실시간으로 다시 로드되는 것을 방지합니다. 이를 통해 서버를 다시 로드하면 일반적으로 버려질 기존 디버거 중단점이 유지됩니다.