Ag cur tús le cód rannchuidithe le Weblate¶

Tuig cód foinse Weblate trí dhul trí: Cód foinse gréasáin, Comhéadan gréasáin agus Inmheánach láithreán gréasáin.

Ag tosú leis an codebase¶

Cuir tú féin ar an eolas faoi bhunachar cód Weblate, trí thriail a dhéanamh ar na fabhtanna a bhfuil an lipéad orthu good first issue.

Tá fáilte romhat tosú ag obair ar na saincheisteanna seo gan ceist a chur. Díreach é sin a fhógairt san eagrán, ionas go mbeidh sé soiléir go bhfuil duine éigin ag obair ar an gceist sin.

Weblate a rith go háitiúil¶

Is é an cur chuige is compordaí chun tús a chur le forbairt Weblate ná Suiteáil ó fhoinsí a leanúint. Gheobhaidh tú timpeallacht Python le foinsí Weblate in-eagarthóireachta leis.

Clón an cód foinse Weblate:

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

Suiteáil Weblate agus gach spleáchas atá úsáideach le haghaidh forbartha:
```
uv sync --all-extras --dev
```
Tosaigh freastalaí forbartha:
```
uv run weblate runserver
```
Ag brath ar do chumraíocht, b'fhéidir gur mhaith leat oibrithe Soilire a thosú freisin:
```
uv run ./weblate/examples/celery start
```
Chun tástálacha a rith (féach Tástáil áitiúil ar Weblate le haghaidh tuilleadh sonraí):
```
. scripts/test-database.sh
uv run pytest
```

Coimeádán forbartha le haghaidh tástálacha agus lint¶

Ullmhaíonn an coimeádán forbartha spleáchais Python, PostgreSQL, Valkey, aistriúcháin tiomsaithe agus comhaid statacha chun tástálacha agus seiceálacha 'lint' a rith. Tacaíonn sé le gnáthchlóin agus le 'worktrees' Git nasctha. Bíonn a choimeádáin, a líonra, a bhunachar sonraí, a thimpeallacht fhíorúil agus a thaisclanna féin ag gach 'checkout', gan aon phoirt óstach foilsithe sa phróifíl tástála réamhshocraithe. Ritheann an phróifíl feidhmchláir roghnach Weblate agus oibrithe le haghaidh QA áitiúil le stóráil ar leith agus le poirt 'localhost' a leithdháiltear go dinimiciúil.

Suiteáil Docker leis an mbreiseán Compose, Git, agus Python 3.12 nó níos déanaí ar an óstach. Chun an sreabhadh oibre líne-ordaithe a úsáid, suiteáil Node.js 20 nó níos déanaí agus an Dev Container CLI chomh maith:

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.

Úsáideann Bootstrap an glas spleáchais reoite agus tógann sé lxml agus xmlsec ón bhfoinse, ag meaitseáil CI. Éilíonn an socrú tosaigh rochtain líonra chun íomhánna agus spleáchais a íoslódáil; íoslódálann crúcaí lint a dtimpeallachtaí ar an gcéad úsáid. Tar éis spleáchais a athrú, athrith:

./scripts/devcontainer bootstrap

Cruthaíonn agus imríonn Pytest a bhunachar sonraí tástála nuair a úsáidtear é den chéad uair, agus athúsáideann sé é i rithanna ina dhiaidh sin. Chun é a athchruthú tar éis athruithe imirce nach bhfuil comhoiriúnach, cuir an bratach --create-db le pytest. Ní bhaineann an coimeádán úsáid as na timpeallachtaí fíorúla ar an óstach ná as an gcomhad áitiúil weblate/settings.py.

Le haghaidh tasc ar leith, cruthaigh crann oibre agus cuir tús lena thimpeallacht:

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

Díorthaítear an t-aitheantóir comhshaoil ó chonair absalóideach an tseiceála amach, mar sin caomhnaítear an timpeallacht trí athrú brainsí. Stop nó scrios an timpeallacht sula mbogtar nó sula scriostar a seiceáil amach. Déanann crainn oibre nasctha an t-eolaire meiteashonraí Git comhroinnte a fheistiú ag a chonair bhunaidh freisin; dá bhrí sin, bíonn tionchar ag oibríochtaí Git ar an stór céanna le hoibríochtaí Git óstach. Ní fheistiútear foinsí crainn oibre eile. Díshocraigh COMPOSE_PROJECT_NAME agus an sreabhadh oibre seo á úsáid agat, agus bain a chuid sannadh ó chomhaid .env sa tseiceáil amach, .devcontainer, agus an t-eolaire as a seolann tú na huirlisí. Diúltaíonn an tosú do na sannadh seo toisc gur féidir leo ainm an tionscadail atá sainiúil don tseiceáil amach a shárú.

Chun coimeádáin a stopadh agus a gcuid sonraí a choinneáil, nó chun na coimeádáin agus na himleabhair a scriosadh go sainráite:

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

Ní bhainistíonn na horduithe seo ach timpeallacht tástála an tseiceáil amach reatha. Ní bhaineann siad a chuid comhad foinse ná an timpeallacht feidhmchláir a thosaigh rundev.sh. Roinneann tástálacha a ritheann trí ./rundev.sh test an timpeallacht tástála seo, mar sin bíonn tionchar ag a stopadh ar an dá lainseálaí tástála. Má dhúnann tú an IDE, stopann sé tionscadal Compose an tseiceáil amach ar fad, lena n-áirítear QA an fheidhmchláir, agus coinnítear a shonraí. Ní bhíonn tionchar ag orduithe stop lainseálaí ach ar a bpróifíl roghnaithe. Bain úsáid as --all roimh stop, logs, nó destroy chun an dá phróifíl a bhainistiú san tseiceáil amach.

Má theipeann ar an socrú, bain úsáid as ./scripts/devcontainer doctor chun na cosáin foinse, na naisc seirbhíse, comhsheasmhacht na spleáchas agus na sócmhainní tástála a scrúdú. Tá teorainn ama ag baint le seiceálacha ar ullmhacht seirbhíse. Fanann coimeádáin ar fáil lena scrúdú; is féidir a gcuid logaí a léamh le docker compose:

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

Déanann Git neamhaird den chomhad .devcontainer/compose.local.json a ghintear, agus bíonn cosáin ann a bhaineann go sonrach leis an seiceáil amach. Ná cuir dintiúir ná cumraíocht an óstaigh sa chomhad seo.

Áirítear san íomhá forbartha chomhroinnte Chromium dúchais agus an tiománaí comhfhreagrach uaidh ó stór XtraDeb Ubuntu do na hailtireachtaí ARM agus amd64. Níl leagan sonrach socraithe do na pacáistí córais seo. Chun nuashonruithe brabhsálaí a fháil, déan an íomhá a thógáil arís gan taisce tógála Docker a úsáid agus cruthaigh an coimeádán tástála arís:

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

Chun tús an bhrabhsálaí, luchtú leathanach agus rith JavaScript a fhíorú, nó chun an tacar Selenium atá ann cheana a rith le brabhsálaí riachtanach:

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

Ullmhaíonn browser-test an timpeallacht tástála scoite, ritheann sé diagnóisic brabhsálaí, agus socraíonn sé CI_SELENIUM=1 ionas go dteipeann ar an WebDriver nach bhfuil ar fáil in ionad é a scipeáil. Priontálann sé iomláin tástála pytest agus cúiseanna scipeála, ag caomhnú scipeálacha dlisteanacha agus stádas scoir pytest. Cuirtear argóintí breise chuig pytest; déan --target arís chun cosáin tástála nó aitheantóirí nóid sonracha a roghnú in ionad an mhodúil Selenium réamhshocraithe. Seiceálann doctor --browser an phróifíl tástála trí cheachtar lainseálaí agus tuairiscíonn sé leaganacha brabhsálaí agus tiománaí suiteáilte.

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.

Is iad Linux agus WSL2 — agus cód á tharraingt síos (checkout) i gcóras comhad Linux — na príomhspriocanna. Baineann macOS Docker Desktop agus Codespaces úsáid as an gcumraíocht chéanna, ach ní chlúdaítear iad leis an tástáil bhunúsach (smoke test) CI do Linux. Ní thacaítear le cosáin dhúchasacha Windows ná le deamhain Docker chianda i gcás na nascadh 'host-path' (host-path mounts).

Weblate a rith go háitiúil i Docker¶

Suiteáil Docker leis an mbreiseán Compose, Git, agus Python 3.12 nó níos déanaí ar an óstach. Cuir tús leis an bhfeidhmchlár forbartha leis an ordú seo a leanas:

./rundev.sh

Tá sé seo coibhéiseach le ./scripts/devcontainer --profile app up. Baineann an dá ordú úsáid as an seoladóir céanna agus as an tionscadal Compose céanna agus a úsáidtear sa timpeallacht tástála, gan gá a bheith le Node.js ná le CLI an Dev Container do phróifíl an fheidhmchláir.

Cruthaíonn an seolaitheoir an íomhá forbartha, cuireann sé tús le Weblate agus próisis oibre gréasáin agus Celery á maoirsiú aige, agus taispeánann sé URLanna an fheidhmchláir agus bhosca poist Maildev nuair a bhíonn Weblate réidh. Logáil isteach mar admin leis an bhfocal faire admin. Bíonn an tsuiteáil folamh ar dtús; lean ar aghaidh le Tionscadail agus comhpháirteanna aistriúcháin a chur leis.

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

Chun oibrithe cúlra fíor a thástáil trí thurais iomlána feidhmchláir:

./rundev.sh application-test

Tá sé seo ar fáil freisin mar ./scripts/devcontainer application-test. Tosaíonn sé próifíl an fheidhmchláir agus úsáideann sé a chomhartha API riarthóra chun cartlann chomhpháirteanna beaga a allmhairiú, aistriúchán a shábháil, tiomnú cúlra a iarraidh, agus an comhad Git tiomnaithe a iniúchadh. Ansin seiceálann sé an ZIP onnmhairithe, staitisticí aistriúcháin deiridh san API agus ar leathanach an fheidhmchláir rindreáilte, cuimhne aistriúcháin, agus fógra aistriúcháin a sheachadtar chuig Maildev. Tá giniúint onnmhairithe féin sioncrónach; ní mór a bhfuil ann an obair chúlra atá críochnaithe a léiriú.

Cuireann seiceáil idirbhirt ar leith tasc fíor i scuaine sula ndéantar a shraith daingneáin a thiomnú, fanann sí le hathiarracht, agus fíoraíonn sí athsheachadadh rathúil tar éis an tiomnaithe. Éilíonn an tsraith Celery neamh-dhíocasach agus bróicéir Valkey an fheidhmchláir agus Maildev. Bíonn spriocdhátaí ag pobalbhreitheanna, áirítear a rianaithe siar i dteipeanna tascanna oibrithe, agus priontáileann teipeanna logaí seirbhíse an fheidhmchláir. Ritheann CI na turais seo sa phost forbartha Docker agus i gcrainn oibre scoite comhuaineacha araon.

Cruthaíonn gach rith tionscadal a bhfuil ainm uathúil air (ag tosú le celery-qa-) agus faighteoir fógraí a bhfuil pasfhocal neamh-inúsáidte aige. Fanann na hacmhainní tástála seo ar fáil lena scrúdú, fiú má theipeann ar an bpróiseas; ní dhéantar sonraí atá ann cheana a athshocrú. Bain na tionscadail agus na húsáideoirí seo tríd an bhfeidhmchlár nuair a bheidh an obair críochnaithe, nó rith destroy --yes ar an timpeallacht feidhmchláir atá ceaptha le haghaidh úsáid shealadach.

Is féidir calafoirt athrú tar éis coimeádáin a athchruthú nó a atosú. Bain úsáid as ./rundev.sh restart chun iad a atosú agus a athfhionnachtain; ní féidir le haththosaithe díreacha Docker fearann an fheidhmchláir a thosú. Athúsáideann gnáth-thosaithe coimeádáin gan athrú. Ní atosófar coimeádáin fheidhmchláir go huathoibríoch tar éis atosú Docker. Nuair a athraíonn an íomhá leaganacha beaga de Python, athchruthaíonn an tosaithe timpeallacht fhíorúil an fheidhmchláir agus athshuiteálann sé spleáchais. Coinnítear sonraí an fheidhmchláir.

Chun rochtain a fháil ar bhunachar sonraí an fheidhmchláir ó taobh istigh dá choimeádán:

./rundev.sh exec -- weblate dbshell

Tá sainmhínithe na seirbhísí feidhmchláir le fáil i dev-docker/docker-compose.yml agus tá siad san áireamh sa chumraíocht chomhroinnte Compose. Bain úsáid as na seoltairí chun cosáin agus poirt a thúsú. Maidir le hoibríochtaí Compose eile, bain úsáid as ./rundev.sh compose -- COMMAND (nó aicearraí atá ann cheana féin, ar nós ./rundev.sh ps). Is féidir le horduithe Compose a bhaineann leis an tionscadal ina iomláine dul i bhfeidhm ar an dá phróifíl.

Ní dhéantar imirce uathoibríoch ar thimpeallachtaí forbartha atá ann cheana. Sula ndéantar nuashonrú ón tsean-seolaitheoir, stop a chuid coimeádán leis an ordú ./rundev.sh stop. Má tá an nuashonrú déanta cheana féin, aimsigh na seanchoimeádáin ag baint úsáide as docker ps agus stop iad go sainráite. Fágann an seolaitheoir nua a gcuid bunachar sonraí, imleabhar agus an eolaire dev-docker/data/ gan teagmháil agus tosaíonn sé le sonraí feidhmchláir úra.

Chun tástálacha a rith, rith an script leis an bparaiméadar test agus le hargóintí pytest; mar shampla, chun gan ach na tástálacha sa mhodúl weblate.machine a rith:

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

Cuireann an t-ordú tús go huathoibríoch leis an gcoimeádán forbartha agus déanann sé é a thúsú (bootstrapping) ag baint úsáide as Docker Compose, gan gá a bheith leis an Dev Container CLI. Ritheann sé go neamhspleách ar an bhfeidhmchlár agus ar na hoibrithe (workers), agus é ag baint úsáide as bunachair shonraí, timpeallachtaí fíorúla agus taisclanna ar leith. Le gach rith, déantar na spleáchais agus na sócmhainní tástála a athnuachan sula rithetar pytest.

Chun logaí an fheidhmchláir a thaispeáint:

./rundev.sh logs

Chun próifíl an fheidhmchláir amháin a stopadh, agus a sonraí a choinneáil:

./rundev.sh stop

Úsáid ./scripts/devcontainer stop chun na tástálacha amháin a stopadh. Chun an dá phróifíl a stopadh nó a scriosadh — lena n-áirítear a gcuid imleabhar agus iad á scriosadh:

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

Gan --all, ní bhaineann destroy --yes ach coimeádáin agus imleabhair an phróifíl roghnaithe amach. Fanann na crainn oibre eile ag rith.

Warning

Níl an coimeádán seo oiriúnach le húsáid táirgthe. Déantar slándáil a íobairt chun an fhorbairt a dhéanamh níos éasca.

Bootstrapping do shampla forbartha¶

Seans gur mhaith leat import_demo a úsáid chun aistriúcháin taispeána a chruthú agus createadmin chun úsáideoir riaracháin a dhéanamh.

Más rud é go bhfuil Billeáil suiteáilte agat chomh maith, is féidir leat billing_demo a úsáid chun tionscadal billeála taispeána a chruthú.

Códú Gréasán le PyCharm¶

Is IDE aitheanta é PyCharm do Python, seo roinnt treoirlínte chun cabhrú leat do thionscadal Weblate a chur ar bun ann.

Ós rud é go bhfuil tú díreach tar éis an stór GitHub a chlónáil go fillteán, níl le déanamh ach é a oscailt le PyCharm. Nuair a bheidh an IDE oscailte, is é an chéad chéim ná an ateangaire a theastaíonn uait a úsáid a shonrú:

Roghnaigh an timpeallacht .venv a chruthaigh uv sync --all-extras --dev chun go n-oirfidh sí don socrú forbartha líne ordaithe. Is féidir leat ligean do PyCharm timpeallacht Python a chruthú duit freisin, ach is fearr an timpeallacht bainistithe uv:

Ná déan dearmad na spleáchais a shuiteáil nuair a bheidh an léirmhínitheoir socraithe. Agus an timpeallacht uv-bhainistithe is fearr leat á húsáid, rith uv sync --all-extras --dev ón gconsól.

Is é an dara céim ná an fhaisnéis cheart a shocrú chun Django a úsáid go dúchais taobh istigh de PyCharm: Is é an smaoineamh a bheith in ann na tástálacha aonaid sa IDE a spreagadh láithreach. Chuige sin ní mór duit bunchosán an tionscadail Django agus an cosán chuig a chuid socruithe a shonrú:

Bí cúramach, is é fréamh iarbhír an stór an Django project root, ní fo-eolaire Weblate. Maidir leis na socruithe, d'fhéadfá an weblate/settings_test.py a úsáid ón stór, ach d'fhéadfá do shuíomh féin a chruthú agus é a shocrú ansin.

Is í an chéim dheireanach ná an freastalaí a rith agus brisphointí a chur sa chód le bheith in ann é a dhífhabhtú. Déantar é seo trí chumraíocht nua Freastalaí Django a chruthú:

Hint

Bí cúramach leis an maoin ar a dtugtar Gan athlódáil: Cuireann sé cosc ar an bhfreastalaí a athlódáil beo má athraíonn tú comhaid. Ligeann sé seo do na brisphointí dífhabhtóra atá ann cheana féin leanúint ar aghaidh, nuair a bheadh siad curtha i leataobh de ghnáth ar athlódáil an fhreastalaí.