# ເລີ່ມປະກອບສ່ວນລະຫັດໃຫ້ Weblate

ເຂົ້າໃຈ Weblate source code ໂດຍການອ່ານ [ຊໍສ໌ໂຄ້ດ Weblate](https://docs.weblate.org/lo/latest/contributing/code.md), [Weblate frontend](https://docs.weblate.org/lo/latest/contributing/frontend.md) ແລະ [ພາຍໃນ Weblate (Internals)](https://docs.weblate.org/lo/latest/contributing/internals.md).

## ເລີ່ມຕົ້ນກັບ Codebase

ເຮັດຄວາມຄຸ້ນເຄີຍກັບ Weblate codebase, ໂດຍການທົດລອງແກ້ໄຂບັນຫາທີ່ຕິດປ້າຍ [good first issue](https://github.com/WeblateOrg/weblate/labels/good%20first%20issue).

ທ່ານສາມາດເລີ່ມເຮັດວຽກກັບ Issue ເຫຼົ່ານີ້ໄດ້ໂດຍບໍ່ຕ້ອງຖາມ. ພຽງແຕ່ປະກາດໃນ Issue ນັ້ນ, ເພື່ອໃຫ້ຊັດເຈນວ່າມີຄົນກຳລັງເຮັດວຽກກັບ Issue ນັ້ນຢູ່.

## ການຮັນ Weblate ໃນເຄື່ອງຂອງທ່ານ (Locally)

ວິທີທີ່ສະດວກສະບາຍທີ່ສຸດໃນການເລີ່ມຕົ້ນການພັດທະນາ Weblate ຄືການປະຕິບັດຕາມ [ການຕິດຕັ້ງຈາກແຫຼ່ງລະຫັດ (Source)](https://docs.weblate.org/lo/latest/admin/install/source.md). ມັນຈະເຮັດໃຫ້ທ່ານມີສະພາບແວດລ້ອມ Python ພ້ອມກັບ Source ຂອງ Weblate ທີ່ສາມາດແກ້ໄຂໄດ້.

1. Clone Weblate source code:
   ```sh
   git clone https://github.com/WeblateOrg/weblate.git
   cd weblate
   ```
2. ຕິດຕັ້ງ Weblate ແລະ Dependencies ທັງໝົດທີ່ມີປະໂຫຍດສຳລັບການພັດທະນາ:
   ```sh
   uv sync --all-extras --dev
   ```
3. ເລີ່ມຕົ້ນເຊີບເວີການພັດທະນາ:
   ```sh
   uv run weblate runserver
   ```
4. ຂຶ້ນຢູ່ກັບການຕັ້ງຄ່າຂອງທ່ານ, ທ່ານອາດຈະຕ້ອງການເລີ່ມຕົ້ນ Celery workers:
   ```sh
   uv run ./weblate/examples/celery start
   ```
5. ເພື່ອດຳເນີນການທົດສອບ (ເບິ່ງ [ການທົດສອບ Weblate ໃນເຄື່ອງ (Locally)](https://docs.weblate.org/lo/latest/contributing/tests.md#local-tests) ສຳລັບລາຍລະອຽດເພີ່ມເຕີມ):
   ```sh
   . scripts/test-database.sh
   uv run pytest
   ```

#### SEE ALSO
[ການຕິດຕັ້ງຈາກແຫຼ່ງລະຫັດ (Source)](https://docs.weblate.org/lo/latest/admin/install/source.md)

<a id="devcontainer"></a>

## 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](#dev-docker) 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:

```sh
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:

```sh
./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:

```sh
./scripts/devcontainer bootstrap
```

Bootstrap also prepares English and orientation OCR models. Subsequent OCR
tests using these models do not need to download them. Diagnostics check the
prepared dependency inputs, Python version, tool caches, and required tools.
After changing the development Dockerfile, run `./scripts/devcontainer build`
and `./scripts/devcontainer restart` to rebuild and recreate the container.

Run broader verification explicitly after starting the environment:

```sh
./scripts/devcontainer verify
./scripts/devcontainer verify --check docs --check frontend
```

The available checks are `lint` (all pre-commit hooks and pylint), `types`
(mypy with the same filtering and enforcement as CI), `docs` (documentation
extension tests and a strict English documentation build), and `frontend`
(a frozen-lockfile install and client asset build). Without `--check`, all
groups run. Independent groups continue after failures and the command fails
if any group fails. Pre-commit hooks can leave formatting fixes in the checkout
for review. Frontend build output goes into a temporary directory, preserving
tracked vendor assets. The image provides Graphviz, Node.js 26, npm, and Yarn
Classic; client dependencies are installed only when requested.

Verification does not synchronize Python dependencies or refresh test assets.
If diagnostics report stale preparation, rerun bootstrap first. Initial lint
and frontend checks require network access for hook environments and JavaScript
dependencies; documentation builds can fetch external reference inventories.

To verify a populated upgrade from a historical release:

```sh
./scripts/devcontainer migration-test 5.10
./scripts/devcontainer migration-test 5.14
```

Each invocation snapshots the current working tree, including tracked edits
and non-ignored untracked files, into an independent temporary clone. It runs
the existing migration CI setup and upgrade assertions with a dedicated Compose
project and database. The optional migration image includes Python 3.11 and
3.13 and legacy rendering dependencies. Release tags and historical dependencies
require network access. The command always uses Docker Compose internally;
it does not require the Dev Container CLI or a running test environment.

Migration verification prints service logs on failure and removes its temporary
clone, containers, and volumes on completion or interruption. It preserves the
caller's branch, index, files, and existing test and application databases.
Run it once per source release that needs verification. Abrupt host shutdown or
an uncatchable process termination can still require manual Docker cleanup.

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:

```sh
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:

```sh
./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**:

```sh
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:

```sh
./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:

```sh
./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.

<a id="dev-docker"></a>

## ການຮັນ Weblate ໃນເຄື່ອງຂອງທ່ານໂດຍໃຊ້ Docker

Install Docker with the Compose plugin, Git, and Python 3.12 or newer on the
host. Start the development application with:

```sh
./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 [ການເພີ່ມໂຄງການແປ ແລະ ອົງປະກອບ](https://docs.weblate.org/lo/latest/admin/projects.md#adding-projects).

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:

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

To exercise real background workers through complete application journeys:

```sh
./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:

```sh
./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:

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

The command automatically starts and bootstraps the [development container](#devcontainer) 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:

```sh
./rundev.sh logs
```

To stop only the application profile, retaining its data:

```sh
./rundev.sh stop
```

Use `./scripts/devcontainer stop` to stop only tests. To stop or destroy both
profiles, including their volumes when destroying:

```sh
./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.

#### WARNING
Container ນີ້ບໍ່ເໝາະສົມສຳລັບການໃຊ້ງານໃນລະບົບຈິງ (Production). ຄວາມປອດໄພຖືກເສຍສະຫຼະເພື່ອເຮັດໃຫ້ການພັດທະນາງ່າຍຂຶ້ນ.

<a id="devel-demo"></a>

## ການເລີ່ມຕົ້ນລະບົບພັດທະນາຂອງທ່ານ

ທ່ານອາດຈະຕ້ອງການໃຊ້ [`import_demo`](https://docs.weblate.org/lo/latest/admin/management.md#weblate-admin-import_demo) ເພື່ອສ້າງການແປສາທິດ (demo) ແລະ [`createadmin`](https://docs.weblate.org/lo/latest/admin/management.md#weblate-admin-createadmin) ເພື່ອສ້າງຜູ້ໃຊ້ Admin.

ຖ້າທ່ານມີ [ການຮຽກເກັບເງິນ](https://docs.weblate.org/lo/latest/admin/optionals.md#billing) ຕິດຕັ້ງໄວ້ເຊັ່ນກັນ, ທ່ານສາມາດໃຊ້ [`billing_demo`](https://docs.weblate.org/lo/latest/admin/management.md#weblate-admin-billing_demo) ເພື່ອສ້າງໂຄງການ Billing ສາທິດ.

## ການຂຽນ Weblate ດ້ວຍ PyCharm

PyCharm ແມ່ນ IDE ທີ່ຮູ້ຈັກກັນດີສຳລັບ Python, ນີ້ແມ່ນຂໍ້ແນະນຳບາງຢ່າງທີ່ຈະຊ່ວຍໃຫ້ທ່ານຕັ້ງຄ່າໂຄງການ Weblate ໃນນັ້ນ.

ສົມມຸດວ່າທ່ານຫາກໍ່ Clone GitHub repository ໃສ່ໂຟນເດີໜຶ່ງແລ້ວ, ພຽງແຕ່ເປີດມັນດ້ວຍ PyCharm. ເມື່ອ IDE ເປີດຂຶ້ນມາ, ຂັ້ນຕອນທຳອິດແມ່ນການລະບຸ Interpreter ທີ່ທ່ານຕ້ອງການໃຊ້:

![image](images/pycharm-1.png)

ເລືອກສະພາບແວດລ້ອມ `.venv` ທີ່ສ້າງຂຶ້ນໂດຍ `uv sync --all-extras --dev` ເພື່ອໃຫ້ກົງກັບການຕັ້ງຄ່າການພັດທະນາຜ່ານ Command-line. ທ່ານຍັງສາມາດປ່ອຍໃຫ້ PyCharm ສ້າງສະພາບແວດລ້ອມ Python ໃຫ້ທ່ານໄດ້, ແຕ່ສະພາບແວດລ້ອມທີ່ຈັດການໂດຍ uv ແມ່ນແນະນຳຫຼາຍກວ່າ:

![image](images/pycharm-2.png)

ຢ່າລືມຕິດຕັ້ງ Dependencies ຫຼັງຈາກຕັ້ງ Interpreter ແລ້ວ. ເມື່ອໃຊ້ສະພາບແວດລ້ອມທີ່ຈັດການໂດຍ uv ທີ່ແນະນຳ, ໃຫ້ດຳເນີນຄຳສັ່ງ `uv sync --all-extras --dev` ຈາກ Console.

ຂັ້ນຕອນທີສອງແມ່ນການຕັ້ງຂໍ້ມູນທີ່ຖືກຕ້ອງເພື່ອໃຊ້ Django ແບບ Native ພາຍໃນ PyCharm: ແນວຄວາມຄິດແມ່ນເພື່ອໃຫ້ສາມາດຮັນ Unit tests ໃນ IDE ໄດ້ທັນທີ. ສຳລັບເລື່ອງນັ້ນ ທ່ານຕ້ອງລະບຸ Path ຫຼັກ (Root path) ຂອງໂຄງການ Django ແລະ Path ໄປຍັງ Settings ຂອງມັນ:

![image](images/pycharm-3.png)

ໃຫ້ລະວັງ, Django project root ແມ່ນ Root ທີ່ແທ້ຈິງຂອງ Repository, ບໍ່ແມ່ນ Weblate sub-directory. ກ່ຽວກັບ Settings, ທ່ານສາມາດໃຊ້ `weblate/settings_test.py` ຈາກ Repository, ແຕ່ທ່ານກໍສາມາດສ້າງ Settings ຂອງທ່ານເອງ ແລະ ຕັ້ງມັນໄວ້ທີ່ນັ້ນ.

ຂັ້ນຕອນສຸດທ້າຍແມ່ນການຮັນເຊີບເວີ ແລະ ວາງ Breakpoints ໃນລະຫັດເພື່ອໃຫ້ສາມາດ Debug ໄດ້. ສິ່ງນີ້ເຮັດໄດ້ໂດຍການສ້າງການຕັ້ງຄ່າ Django Server ໃໝ່:

![image](images/pycharm-4.png)![image](images/pycharm-5.png)

#### HINT
ໃຫ້ລະວັງຄຸນສົມບັດທີ່ເອີ້ນວ່າ No reload: ມັນປ້ອງກັນບໍ່ໃຫ້ເຊີບເວີ Reload ແບບສົດໆຖ້າທ່ານແກ້ໄຂໄຟລ໌. ສິ່ງນີ້ຊ່ວຍໃຫ້ Breakpoints ຂອງ Debugger ທີ່ມີຢູ່ຍັງຄົງຢູ່, ໃນຂະນະທີ່ປົກກະຕິພວກມັນຈະຖືກຍົກເລີກເມື່ອ Reload ເຊີບເວີ.
