# Začíname prispievať kódom do Weblate

Pochopte zdrojový kód Weblate preštudovaním [Zdrojový kód Weblate](https://docs.weblate.org/sk/latest/contributing/code.md), [Frontend Weblate](https://docs.weblate.org/sk/latest/contributing/frontend.md) a [Vnútorná štruktúra Weblate](https://docs.weblate.org/sk/latest/contributing/internals.md).

## Začíname s kódovou základňou

Oboznámte sa s kódovou základňou Weblate tým, že sa pokúsite vyriešiť chyby označené ako [good first issue](https://github.com/WeblateOrg/weblate/labels/good%20first%20issue).

Môžete začať pracovať na týchto problémoch bez opýtania. Len to oznámte v probléme, aby bolo jasné, že niekto na tomto probléme pracuje.

## Spúšťanie Weblate lokálne

Najpohodlnejší prístup, ako začať s vývojom Weblate, je postupovať podľa [Inštalácia zo zdrojových kódov](https://docs.weblate.org/sk/latest/admin/install/source.md). Získate prostredie Python s upraviteľnými zdrojmi Weblate.

1. Klonujte zdrojový kód Weblate:
   ```sh
   git clone https://github.com/WeblateOrg/weblate.git
   cd weblate
   ```
2. Nainštalujte Weblate a všetky závislosti užitočné pre vývoj:
   ```sh
   uv sync --all-extras --dev
   ```
3. Spustite vývojový server:
   ```sh
   uv run weblate runserver
   ```
4. V závislosti od vašej konfigurácie môžete chcieť spustiť aj pracovníkov Celery:
   ```sh
   uv run ./weblate/examples/celery start
   ```
5. Na spustenie testov (viac podrobností nájdete v [Lokálne testovanie Weblate](https://docs.weblate.org/sk/latest/contributing/tests.md#local-tests)):
   ```sh
   . scripts/test-database.sh
   uv run pytest
   ```

#### SEE ALSO
[Inštalácia zo zdrojových kódov](https://docs.weblate.org/sk/latest/admin/install/source.md)

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

## Vývojový kontajner pre testy a lint

Vývojový kontajner pripravuje závislosti Pythonu, PostgreSQL, Valkey, skompilované preklady a statické súbory na spúšťanie testov a kontrol lint. Podporuje bežné klony a prepojené pracovné stromy Git. Každý checkout má svoje vlastné kontajnery, sieť, databázu, virtuálne prostredie a cache, pričom v predvolenom teste profilu nie sú publikované žiadne porty hostiteľa. Voliteľný profil aplikácie spúšťa [Weblate a pracovníkov pre lokálnu QA](#dev-docker) s oddeleným úložiskom a dynamicky pridelenými portmi localhost.

Nainštalujte Docker s pluginom Compose, Git a Python 3.12 alebo novší na hostiteľovi. Pre pracovný postup príkazového riadka tiež nainštalujte Node.js 20 alebo novší a CLI Dev Container:

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

Prípadne otvorte checkout vo Visual Studio Code s jeho rozšírením Dev Containers a vyberte Dev Containers: Znovu otvoriť v kontajneri. Oba pracovné postupy používajú `.devcontainer/devcontainer.json` a čakajú na dokončenie bootstrapu. CLI musí byť nainštalované samostatne pre predvolený backend `scripts/devcontainer`. Ak chcete použiť Docker Compose priamo bez Node.js alebo CLI Dev Container, zadajte `--backend compose` pred príkazom:

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

Oba backendy zdieľajú rovnaké testovacie prostredie pre checkout. Backend Compose spúšťa bootstrap pri každom vyvolaní `up`. CI kontroluje oba backendy na behových prostrediach ARM Linux, vrátane súbežnej QA aplikácie v samostatných pracovných stromoch.

Bootstrap používa zamknuté závislosti a zostavuje `lxml` a `xmlsec` zo zdrojového kódu, čo zodpovedá CI. Počiatočné nastavenie vyžaduje prístup k sieti na stiahnutie obrazov a závislostí; háky lint si sťahujú svoje prostredia pri prvom použití. Po zmene závislostí znovu spustite:

```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 vytvorí a migruje svoju testovaciu databázu pri prvom použití a znovu ju použije pri následných spusteniach. Na jej znovu vytvorenie po nekompatibilných zmenách migrácie zadajte pytestu `--create-db`. Kontajner nepoužíva existujúce virtuálne prostredia hostiteľa ani lokálny `weblate/settings.py`.

Pre samostatnú úlohu vytvorte pracovný strom (worktree) a spustite jeho prostredie:

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

Identifikátor prostredia je odvodený z absolútnej cesty checkoutu, takže zmena vetiev zachováva prostredie. Pred presunutím alebo vymazaním checkoutu zastavte alebo zničte prostredie. Prepojené pracovné stromy tiež montujú zdieľaný adresár metadát Git na jeho pôvodnej ceste; operácie Git preto ovplyvňujú ten istý repozitár ako operácie Git hostiteľa. Zdroje iných pracovných stromov nie sú namontované. Pri používaní tohto pracovného postupu zrušte nastavenie `COMPOSE_PROJECT_NAME` a odstráňte jeho priradenia zo súborov `.env` v checkoute, `.devcontainer` a adresári, z ktorého spúšťate nástroje. Inicializácia tieto priradenia odmieta, pretože môžu prepísať názov projektu špecifický pre checkout.

Ak chcete zastaviť kontajnery pri zachovaní ich údajov alebo explicitne vymazať ich kontajnery a zväzky:

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

Tieto príkazy spravujú iba testovacie prostredie aktuálneho checkoutu. Neodstraňujú jeho zdrojové súbory ani aplikačné prostredie spustené pomocou `rundev.sh`. Testy spustené cez `./rundev.sh test` zdieľajú toto testovacie prostredie, takže ich zastavenie ovplyvní oba spúšťače testov. Zatvorenie IDE zastaví celý projekt Compose checkoutu, vrátane QA aplikácie, pričom zachováva jeho údaje. Príkazy na zastavenie spúšťača ovplyvňujú iba ich vybraný profil. Použite `--all` pred `stop`, `logs` alebo `destroy` na správu oboch profilov v checkoute.

Ak nastavenie zlyhá, použite `./scripts/devcontainer doctor` na kontrolu ciest zdrojov, pripojení služieb, konzistencie závislostí a testovacích aktív. Kontroly pripravenosti služby majú časový limit. Kontajnery zostávajú dostupné na kontrolu; ich logy možno čítať pomocou **docker compose**:

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

Generovaný `.devcontainer/compose.local.json` je ignorovaný Gitom a obsahuje cesty špecifické pre checkout. Do tohto súboru neuchovávajte poverenia ani konfiguráciu hostiteľa.

Zdieľaný vývojový obraz obsahuje natívny Chromium a jeho zodpovedajúci ovládač z úložiska XtraDeb Ubuntu pre ARM a amd64. Tieto systémové balíky nie sú viazané na verziu. Ak chcete získať aktualizácie prehliadača, znovu zostavte bez cache zostavenia Docker a znovu vytvorte testovací kontajner:

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

Na overenie spustenia prehliadača, načítania stránky a vykonávania JavaScriptu alebo na spustenie existujúcej sady Selenium s požadovaným prehliadačom:

```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` pripravuje izolované testovacie prostredie, spúšťa diagnostiku prehliadača a nastavuje `CI_SELENIUM=1`, aby nedostupný WebDriver zlyhal namiesto preskočenia. Vypisuje súčty testov pytest a dôvody preskočenia, pričom zachováva legitímne preskočenia a stav ukončenia pytest. Ďalšie argumenty sa odovzdávajú pytest; opakujte `--target` na výber konkrétnych ciest testov alebo ID uzlov namiesto predvoleného modulu Selenium. `doctor --browser` kontroluje testovací profil cez ktorýkoľvek spúšťač a hlási nainštalované verzie prehliadača a ovládača.

Obraz nastavuje `WEBLATE_TEST_CHROME_BINARY` a `WEBLATE_TEST_CHROMEDRIVER` na nainštalované cesty spustiteľných súborov. Tieto premenné určené iba pre vývojárov zdieľajú diagnostické testy a testy Selenium, čím sa vyhýbajú automatickému sťahovaniu prehliadača. Mimo obrazu ich ponechanie nenastavené zachováva predvolené objavovanie prehliadača Selenium. Na exploratórnu QA použite svoj vlastný prehliadač s URL profilu aplikácie.

Primárnymi cieľmi sú Linux a WSL2 s checkoutom v súborovom systéme Linux. macOS Docker Desktop a Codespaces používajú rovnakú konfiguráciu, ale nie sú pokryté testom dymu Linux CI. Natívne cesty Windows a vzdialené démoni Docker nie sú podporované montážami host-path.

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

## Spúšťanie Weblate lokálne v Dockeri

Nainštalujte Docker s pluginom Compose, Git a Python 3.12 alebo novší na hostiteľovi. Spustite vývojovú aplikáciu pomocou:

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

Toto je ekvivalentné `./scripts/devcontainer --profile app up`. Obidva príkazy používajú rovnaký spúšťač a projekt Compose ako testovacie prostredie, bez potreby Node.js alebo CLI Dev Container pre profil aplikácie.

Spúšťač zostaví vývojový obraz, spustí Weblate s monitorovanými webovými a Celery pracovníkmi a vypíše URL aplikácie a poštovej schránky Maildev, keď je Weblate pripravený. Prihláste sa ako `admin` s heslom `admin`. Inštalácia začína prázdna; pokračujte s [Pridávanie prekladových projektov a komponentov](https://docs.weblate.org/sk/latest/admin/projects.md#adding-projects).

Docker prideľuje voľné HTTP porty viazané na `127.0.0.1`. Každý pracovný strom má svoju vlastnú aplikačnú databázu, inštanciu Valkey, údaje, virtuálne prostredie, domovský adresár a cache, oddelené od testovacieho profilu. Porty SMTP, PostgreSQL a Valkey nie sú publikované. Weblate používa objavenú URL aplikácie pre generované odkazy a pôvody autentifikácie. Na opätovné zobrazenie aktuálnych URL:

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

Na precvičenie skutočných pracovníkov na pozadí prostredníctvom kompletných aplakačných ciest:

```sh
./rundev.sh application-test
```

Toto je tiež dostupné ako `./scripts/devcontainer application-test`. Spustí profil aplikácie a použije jeho administrátorský token API na import malého archívu komponentu, uloženie prekladu, vyžiadanie zápisu na pozadí a kontrolu zapísaného súboru Git. Potom skontroluje exportovaný ZIP, prípadné štatistiky prekladu v API a vykreslenej stránke aplikácie, prekladovú pamäť a notifikačný e-mail o preklade doručený do Maildev. Generovanie exportu samo o sebe je synchronné; jeho obsah musí odrážať dokončenú prácu na pozadí.

Samostatná kontrola transakcie zaradí skutočnú úlohu pred commitom jej fixtačného riadku, čaká na opakovanie a overí úspešné opätovné doručenie po commite. Sada vyžaduje ne-chamtivý Celery a broker Valkey aplikácie a Maildev. Dotazy majú lehoty, zlyhania úloh pracovníkov zahŕňajú ich tracebacky a zlyhania vypisujú logy aplikačnej služby. CI spúšťa tieto cesty v úlohe vývoja Docker aj v súbežných izolovaných pracovných stromoch.

Každé vyvolanie vytvorí jedinečne pomenovaný projekt `celery-qa-` a príjemcu notifikácie s nepoužiteľným heslom. Tieto fixtácie zostávajú dostupné na kontrolu, vrátane po zlyhaní; sada nerešetuje existujúce údaje. Po dokončení odstráňte tieto projekty a používateľov prostredníctvom aplikácie alebo **destroy --yes** jednorazové aplikačné prostredie.

Porty sa môžu zmeniť po znovu vytvorení alebo reštartovaní kontajnerov. Použite `./rundev.sh restart` na reštart a znovuobjavenie; priame reštarty Docker nemôžu inicializovať doménu aplikácie. Bežné spustenie znovu používa nezmenené kontajnery. Aplikačné kontajnery sa po reštartoch Docker neštartujú automaticky. Keď obraz zmení menšie verzie Pythonu, spustenie znovu vytvorí virtuálne prostredie aplikácie a znovu nainštaluje závislosti. Údaje aplikácie sa zachovávajú.

Na prístup k aplikačnej databáze zvnútra jej kontajnera:

```sh
./rundev.sh exec -- weblate dbshell
```

Definície aplikačných služieb sú v `dev-docker/docker-compose.yml` a sú zahrnuté zdieľanou konfiguráciou Compose. Na inicializáciu ciest a portov použite spúšťače. Pre ostatné operácie Compose použite `./rundev.sh compose -- PRÍKAZ` (alebo existujúce skratky, ako je `./rundev.sh ps`). Príkazy Compose pre celý projekt môžu ovplyvniť oba profily.

Existujúce vývojové prostredia sa nemigrujú automaticky. Pred aktualizáciou zo starého spúšťača zastavte jeho kontajnery príkazom `./rundev.sh stop`. Ak už boli aktualizované, identifikujte staré kontajnery pomocou `docker ps` a explicitne ich zastavte. Nový spúšťač ponecháva ich databázy, zväzky a `dev-docker/data/` nedotknuté a začína s čerstvými údajmi aplikácie.

Na vykonanie testov spustite skript s parametrom `test` a argumentmi pytest, napríklad spustením iba testov v module `weblate.machine`:

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

Príkaz automaticky spustí a inicializuje [vývojový kontajner](#devcontainer) pomocou Docker Compose, bez potreby CLI Dev Container. Beží nezávisle od aplikácie a pracovníkov, s oddelenými databázami, virtuálnymi prostrediami a cache. Každé vyvolanie obnoví závislosti a testovacie aktíva pred spustením pytest.

Na zobrazenie logov aplikácie:

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

Na zastavenie iba profilu aplikácie pri zachovaní jej údajov:

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

Použite `./scripts/devcontainer stop` na zastavenie iba testov. Na zastavenie alebo zničenie oboch profilov, vrátane ich zväzkov pri ničení:

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

Bez `--all`, `destroy --yes` odstráni iba kontajnery a zväzky vybraného profilu. Ostatné pracovné stromy zostávajú bežať.

#### WARNING
Tento kontajner nie je vhodný na produkčné použitie. Bezpečnosť je obetovaná, aby sa vývoj uľahčil.

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

## Inicializácia vašej vývojovej inštancie

Môžete chcieť použiť [`import_demo`](https://docs.weblate.org/sk/latest/admin/management.md#weblate-admin-import_demo) na vytvorenie demo prekladov a [`createadmin`](https://docs.weblate.org/sk/latest/admin/management.md#weblate-admin-createadmin) na vytvorenie administrátora.

Ak máte nainštalovaný aj [Fakturácia](https://docs.weblate.org/sk/latest/admin/optionals.md#billing), môžete použiť [`billing_demo`](https://docs.weblate.org/sk/latest/admin/management.md#weblate-admin-billing_demo) na vytvorenie demo fakturačného projektu.

## Kódovanie Weblate s PyCharm

PyCharm je známe IDE pre Python, tu sú niektoré smernice, ktoré vám pomôžu nastaviť váš projekt Weblate v ňom.

Vzhľadom na to, že ste práve naklonovali repozitár GitHub do priečinka, jednoducho ho otvorte s PyCharm. Keď je IDE otvorené, prvým krokom je špecifikovať interpret, ktorý chcete použiť:

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

Vyberte prostredie `.venv` vytvorené pomocou `uv sync --all-extras --dev`, aby zodpovedalo nastaveniu vývoja z príkazového riadka. Môžete tiež nechať PyCharm vytvoriť prostredie Python za vás, ale uprednostňuje sa prostredie spravované pomocou uv:

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

Nezabudnite nainštalovať závislosti po nastavení interpreta. Pri použití uprednostňovaného prostredia spravovaného pomocou uv spustite `uv sync --all-extras --dev` z konzoly.

Druhým krokom je nastaviť správne informácie na natívne použitie Django v PyCharm: Myšlienkou je mať možnosť okamžite spustiť jednotkové testy v IDE. Na to potrebujete špecifikovať koreňovú cestu projektu Django a cestu k jeho nastaveniam:

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

Dávajte pozor, koreň projektu Django je skutočný koreň repozitára, nie podadresár Weblate. Čo sa týka nastavení, mohli by ste použiť `weblate/settings_test.py` z repozitára, ale mohli by ste vytvoriť vlastné nastavenie a nastaviť ho tam.

Posledným krokom je spustiť server a umiestniť breakpointy do kódu, aby ste ho mohli ladiť. Urobí sa to vytvorením novej konfigurácie Django Server:

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

#### HINT
Dávajte pozor na vlastnosť nazvanú No reload: Zabraňuje znovu načítaniu servera za behu, ak upravíte súbory. To umožňuje existujúcim breakpointom ladiča pretrvať, keď by normálne boli zahodené pri znovu načítaní servera.
