Začíname prispievať kódom do Weblate¶
Pochopte zdrojový kód Weblate preštudovaním Zdrojový kód Weblate, Frontend Weblate a Vnútorná štruktúra Weblate.
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.
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. Získate prostredie Python s upraviteľnými zdrojmi Weblate.
Klonujte zdrojový kód Weblate:
git clone https://github.com/WeblateOrg/weblate.git cd weblate
Nainštalujte Weblate a všetky závislosti užitočné pre vývoj:
uv sync --all-extras --dev
Spustite vývojový server:
uv run weblate runserver
V závislosti od vašej konfigurácie môžete chcieť spustiť aj pracovníkov Celery:
uv run ./weblate/examples/celery start
Na spustenie testov (viac podrobností nájdete v Lokálne testovanie Weblate):
. scripts/test-database.sh uv run pytest
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 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:
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:
./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:
./scripts/devcontainer bootstrap
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:
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:
./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:
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:
./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:
./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.
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:
./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.
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:
./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:
./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:
./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:
./rundev.sh test --exitfirst weblate/machine
Príkaz automaticky spustí a inicializuje vývojový kontajner 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:
./rundev.sh logs
Na zastavenie iba profilu aplikácie pri zachovaní jej údajov:
./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í:
./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ť.
Varovanie
Tento kontajner nie je vhodný na produkčné použitie. Bezpečnosť je obetovaná, aby sa vývoj uľahčil.
Inicializácia vašej vývojovej inštancie¶
Môžete chcieť použiť import_demo na vytvorenie demo prekladov a createadmin na vytvorenie administrátora.
Ak máte nainštalovaný aj Fakturácia, môžete použiť 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ť:
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:
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:
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:
Rada
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.