From 130bea7de83eb676c31f715825f53e3cdf0a3fa4 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Tue, 28 Jul 2026 00:36:12 +0200 Subject: [PATCH 1/8] Make README focused on new content translations --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 65d44b632..0447633e8 100644 --- a/README.md +++ b/README.md @@ -25,34 +25,74 @@ f'''[![build](https://github.com/python/python-docs-pl/actions/workflows/update- *Read this in another language: [English](README.en.md)* -**Znalazłem błąd, co mam zrobić?** +**Jak sprawdzić, co jest do przetłumaczenia?** -Jeśli znalazłeś(-aś) błąd lub masz sugestię, -[dodaj zgłoszenie](https://github.com/python/python-docs-pl/issues) w tym projekcie lub -napraw go sam(a): +Służy do tego paczka `potodo`. Wywołaj ją w głównym katalogu projektu, np. `uvx potodo`. + +Jeżeli interesują cię podstawowe artykuły, użyj filtrowania. Przykład: + +``` +$ uvx potodo --exclude '**/*' '!tutorial/*' '!bugs.po' '!library/functions.po'` +1 directory 99.68% done +└── python-docs-pl/ 99.68% done + ├── library/ 98.61% done + │ └── functions.po 99.0% translated 535/536 + └── tutorial/ 100.00% done +``` + +Propozycje priorytetowych zasobów do tłumaczenia można znaleźć w [issue #50](https://github.com/python/python-docs-pl/issues/50). + +**Jak tłumaczyć?** * Wejdź na stronę -projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python-newest/). +projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python-newest/) na Transifeksie. * Naciśnij przycisk „Join this project”, aby dołączyć do projektu. * Utwórz konto Transifex. * Na stronie projektu wybierz język polski. +* Po wysłaniu zgłoszenia do zespołu przedstaw się na kanale [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc). Pozwoli to szybciej potwierdzić Twoje zgłoszenie. * Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. Więcej informacji o używaniu Transifeksa znajdziesz w [jego artykułach pomocy](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) lub [w naszym przewodniku](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). -**Chcę pomóc w tłumaczeniu, ale nie wiem od czego zacząć!** +**Jak lokalnie sprawdzić poprawność moich zmian?** + +Pobierz Transifex CLI i zapisz klucz API Transifex do `.tx/api-key`, aby pobrać zmiany z Transifeksa. Pobierz zmieniony +rozdział, np.: + +``` +$ tx pull --languages pl python-newest.library--turtle +# Getting info about resources -Najpierw dołącz do projektu jako tłumacz, postępując zgodnie z przewodnikiem w poprzedniej sekcji. +python-newest.library--turtle - Done +[##############################] (1 / 1) -Następnie możesz zacząć od tłumaczenia jednego z naszych [priorytetowych zasobów.](https://github.com/python/python-docs-pl/issues/50) +# Pulling files + +python-newest.library--turtle [pl] - Done +[##############################] (1 / 1) +``` + +Uruchom `sphinx-lint`, aby sprawdzić poprawność zmian, np.: + +``` +$ uvx sphinx-lint library/turtle.po +No problems found. +``` **Jak obejrzeć najnowszy build dokumentacji?** Pobierz ostatnią zbudowaną dokumentację z listy artefaktów w ostatniej GitHub Action (zakładka Actions). -Tłumaczenia pobierane są z Transifeksa do tego repozytorium co około pół godziny. +Tłumaczenia pobierane są z Transifeksa do tego repozytorium co około godzinę. Dokumentacja na https://docs.python.org/pl/ aktualizowana jest około raz dziennie. +**Jak zbudować dokumentację?** + +Na Uniksach zrób link symboliczny projektu `python-docs-pl` w katalogu `Doc/locales/pl` on nazwie `LC_MESSAGES`. +Na Windowsie skopiuj zawartość katalogu projektu do podanej ścieżki. + +Następnie uruchom `make -C Doc SPHINXOPTS="-D language=pl" html` w projekcie CPython, aby zbudować dokumentację. + **Kanały komunikacji** * [Discord Python Polska #dokumentacja](https://discord.gg/VCyBDGH38e) @@ -61,7 +101,7 @@ Dokumentacja na https://docs.python.org/pl/ aktualizowana jest około raz dzienn **Postęp tłumaczenia** -Postęp tłumaczenia +Postęp tłumaczenia -**Licencja** +### Licencja Zapraszając do współtworzenia projektu na platformie Transifex, proponujemy umowę na przekazanie twoich tłumaczeń Python Software Foundation @@ -117,17 +119,17 @@ przekazanie twoich tłumaczeń Python Software Foundation W zamian będzie widoczne, że jesteś tłumaczem(-ką) części, którą przetłumaczyłeś(-łaś). Wyrażasz akceptację tej umowy, przesyłając swoją pracę do włączenia do dokumentacji. -**Aktualizacja tłumaczeń** +### Aktualizacje w repozytorium * `./manage_translation.py recreate_tx_config` * `./manage_translation.py fetch` * `cog -rP README.md` -**Przydatne materiały** +### Przydatne materiały * [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/) * [Python docs Transifex: Documentation](https://python-docs-transifex-automation.readthedocs.io/) * [statystyki oglądalności](https://analytics.python.org/docs.python.org?f=contains,page,/pl/) -**Podobne projekty** +### Podobne projekty * [projekty Python Packaging Authority](https://hosted.weblate.org/projects/pypa/-/pl/) * [Scientific Python Translations](https://scientific-python-translations.github.io/) * [micro:bit translation programme](https://microbit.org/translate/) From 9bb722ec1701c86240740e10dbddd1f2b7c73734 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 21 Aug 2026 02:38:16 +0200 Subject: [PATCH 5/8] Port changes to English version --- README.en.md | 82 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/README.en.md b/README.en.md index 295fcd2e3..b20e7732e 100644 --- a/README.en.md +++ b/README.en.md @@ -25,48 +25,92 @@ f'''[![build](https://github.com/python/python-docs-pl/actions/workflows/update- *Przeczytaj to w innym języku: [polski](README.md)* -**I found a mistake, what do I do?** +### How do I check what needs translating? -If you find a mistake or have a suggestion, -[let us know](https://github.com/python/python-docs-pl/issues) or fix it yourself: +Use the `potodo` package. Run it in the project's root directory, for example: `uvx potodo`. -* Go to the website of the project [Python Documentation](https://explore.transifex.com/python-doc/python-newest/). -* Click the button "Join this project", to join the Project. +If you are interested in the core articles, use filtering. For example: + +``` +$ uvx potodo --exclude '**/*' '!tutorial/*' '!bugs.po' '!library/functions.po'` +1 directory 99.68% done +└── python-docs-pl/ 99.68% done + ├── library/ 98.61% done + │ └── functions.po 99.0% translated 535/536 + └── tutorial/ 100.00% done +``` + +Suggested priority resources for translation can be found in [issue #50](https://github.com/python/python-docs-pl/issues/50). + +### How do I translate? + +* Go to the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) on Transifex. +* Click the "Join this project" button. * Create an account on Transifex. -* On the project website pick the language Polish. -* After joining the Project, pick the category you want to fix/translate. +* Select Polish on the project page. +* After submitting your request to join the team, introduce yourself on the [Python Polska #dokumentacja Discord channel](https://discord.gg/QB3h2Sxc). This will help us approve your request sooner. +* After joining the team, select the resource you want to improve or update. You can find more information about using Transifex in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) or [our guide](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). -**I want to start translating, but I don't know where to start!** +### How do I check my changes locally? + +[Install the Transifex CLI](https://github.com/transifex/cli#installation) and save your +[Transifex API token](https://help.transifex.com/en/articles/6248858-generating-an-api-token) to `~/.transifexrc` so that you +can download changes from Transifex. Download the changed chapter, for example: + +``` +$ tx pull --languages pl python-newest.library--turtle +# Getting info about resources + +python-newest.library--turtle - Done +[##############################] (1 / 1) -Firstly, you can join as a translator by following the steps outlined above. +# Pulling files -Then you can start by translating one of our [prioritized resources](https://github.com/python/python-docs-pl/issues/50). +python-newest.library--turtle [pl] - Done +[##############################] (1 / 1) +``` -**How to see the newest build of the documentation?** +Run `sphinx-lint` to check your changes, for example: + +``` +$ uvx sphinx-lint library/turtle.po +No problems found. +``` + +### How do I see the latest build of the documentation? Download the latest build from the list of artefacts in the latest GitHub Action (Actions Tab). -Translations are pulled from Transifex around every half hour. +Translations are pulled from Transifex around once an hour. The documentation at https://docs.python.org/pl/ is updated around once daily. -**Communication Channels** +### How do I build the documentation? + +You need a checkout of the CPython repository to build the documentation. + +Create a symbolic link (Unix) or a copy (Windows) of the `python-docs-pl` project in the CPython repository's +`Doc/locales/pl` directory, named `LC_MESSAGES`. + +Then run `make -C Doc SPHINXOPTS="-D language=pl" html` in the CPython repository to build the documentation. + +### Communication channels * [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc) * [Python Documentation Community](https://docs-community.readthedocs.io/) * [Python Documentation Special Interest Group](https://www.python.org/community/sigs/current/doc-sig/) -**Translation progress** +### Translation progress -Translation progress +Translation progress -**License** +### License By inviting you to work on a project on the Transifex platform, we offer a contract for donating your translations to the Python Software Foundation @@ -74,17 +118,17 @@ donating your translations to the Python Software Foundation In return, it will be visible that you are the translator of the part you translated. You signify your acceptance of this agreement by submitting your work for inclusion in the documentation. -**Updating Translations** +### Repository updates * `./manage_translation.py recreate_tx_config` * `./manage_translation.py fetch` * `cog -rP README.en.md` -**Useful Materials** +### Useful materials * [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/) * [Python docs Transifex: Documentation](https://python-docs-transifex-automation.readthedocs.io/) * [Site Statistics](https://analytics.python.org/docs.python.org?f=contains,page,/pl/) -**Similar Translation Projects** +### Similar projects * [Projects of the Python Packaging Authority](https://hosted.weblate.org/projects/pypa/-/pl/) * [Scientific Python Translations](https://scientific-python-translations.github.io/) * [micro:bit translation programme](https://microbit.org/translate/) From 55704805dee4b0190d249e6fa6fbcb88f959daa7 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sat, 22 Aug 2026 22:00:45 +0200 Subject: [PATCH 6/8] Links to PyPI, newlines after headings, build and contribute section improvements --- README.en.md | 19 ++++++++----------- README.md | 16 +++++++++------- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/README.en.md b/README.en.md index b20e7732e..b73af2954 100644 --- a/README.en.md +++ b/README.en.md @@ -27,7 +27,8 @@ f'''[![build](https://github.com/python/python-docs-pl/actions/workflows/update- ### How do I check what needs translating? -Use the `potodo` package. Run it in the project's root directory, for example: `uvx potodo`. +Use the [`potodo`](https://pypi.org/project/sphinx-lint/) package. Run it in the project's root directory, +for example: `uvx potodo`. If you are interested in the core articles, use filtering. For example: @@ -49,9 +50,7 @@ Suggested priority resources for translation can be found in [issue #50](https:/ * Create an account on Transifex. * Select Polish on the project page. * After submitting your request to join the team, introduce yourself on the [Python Polska #dokumentacja Discord channel](https://discord.gg/QB3h2Sxc). This will help us approve your request sooner. -* After joining the team, select the resource you want to improve or update. - -You can find more information about using Transifex +* After joining the team, select the resource you want to improve or update. You can find more information about using Transifex in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) or [our guide](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). ### How do I check my changes locally? @@ -73,7 +72,7 @@ python-newest.library--turtle [pl] - Done [##############################] (1 / 1) ``` -Run `sphinx-lint` to check your changes, for example: +Run [`sphinx-lint`](https://pypi.org/project/sphinx-lint/) to check your changes, for example: ``` $ uvx sphinx-lint library/turtle.po @@ -88,12 +87,7 @@ The documentation at https://docs.python.org/pl/ is updated around once daily. ### How do I build the documentation? -You need a checkout of the CPython repository to build the documentation. - -Create a symbolic link (Unix) or a copy (Windows) of the `python-docs-pl` project in the CPython repository's -`Doc/locales/pl` directory, named `LC_MESSAGES`. - -Then run `make -C Doc SPHINXOPTS="-D language=pl" html` in the CPython repository to build the documentation. +[See devguide's instructions.](https://devguide.python.org/documentation/translations/translating/#how-do-i-build-a-docs-translation) ### Communication channels @@ -119,16 +113,19 @@ In return, it will be visible that you are the translator of the part you transl You signify your acceptance of this agreement by submitting your work for inclusion in the documentation. ### Repository updates + * `./manage_translation.py recreate_tx_config` * `./manage_translation.py fetch` * `cog -rP README.en.md` ### Useful materials + * [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/) * [Python docs Transifex: Documentation](https://python-docs-transifex-automation.readthedocs.io/) * [Site Statistics](https://analytics.python.org/docs.python.org?f=contains,page,/pl/) ### Similar projects + * [Projects of the Python Packaging Authority](https://hosted.weblate.org/projects/pypa/-/pl/) * [Scientific Python Translations](https://scientific-python-translations.github.io/) * [micro:bit translation programme](https://microbit.org/translate/) diff --git a/README.md b/README.md index a8bebecb1..f108a5459 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ f'''[![build](https://github.com/python/python-docs-pl/actions/workflows/update- ### Jak sprawdzić, co jest do przetłumaczenia? -Służy do tego paczka `potodo`. Wywołaj ją w głównym katalogu projektu, np. `uvx potodo`. +Służy do tego paczka [`potodo`](https://pypi.org/project/potodo/). Wywołaj ją w głównym katalogu projektu, +na przykład `uvx potodo`. Jeżeli interesują cię podstawowe artykuły, użyj filtrowania. Przykład: @@ -50,9 +51,7 @@ projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python- * Utwórz konto Transifex. * Na stronie projektu wybierz język polski. * Po wysłaniu zgłoszenia do zespołu przedstaw się na kanale [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc). Pozwoli to szybciej potwierdzić Twoje zgłoszenie. -* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. - -Więcej informacji o używaniu Transifeksa znajdziesz w +* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. Więcej informacji o używaniu Transifeksa znajdziesz w [jego artykułach pomocy](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) lub [w naszym przewodniku](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). ### Jak lokalnie sprawdzić poprawność moich zmian? @@ -74,7 +73,7 @@ python-newest.library--turtle [pl] - Done [##############################] (1 / 1) ``` -Uruchom `sphinx-lint`, aby sprawdzić poprawność zmian, np.: +Uruchom [`sphinx-lint`](https://pypi.org/project/sphinx-lint/), aby sprawdzić poprawność zmian, na przykład: ``` $ uvx sphinx-lint library/turtle.po @@ -91,8 +90,8 @@ Dokumentacja na https://docs.python.org/pl/ aktualizowana jest około raz dzienn Aby zbudować dokumentację potrzebujesz mieć kopię repozytorium CPythona. -Zrób link symboliczny (Unix) lub kopię (Windows) projektu `python-docs-pl` w katalogu `Doc/locales/pl` repozytorium -CPython, o nazwie `LC_MESSAGES`. +Zrób link symboliczny (Unix) lub kopię (Windows) zawartości projektu `python-docs-pl` w katalogu +`Doc/locales/pl/LC_MESSAGES` w repozytorium CPython. Następnie uruchom `make -C Doc SPHINXOPTS="-D language=pl" html` w projekcie CPython, aby zbudować dokumentację. @@ -120,16 +119,19 @@ W zamian będzie widoczne, że jesteś tłumaczem(-ką) części, którą przet Wyrażasz akceptację tej umowy, przesyłając swoją pracę do włączenia do dokumentacji. ### Aktualizacje w repozytorium + * `./manage_translation.py recreate_tx_config` * `./manage_translation.py fetch` * `cog -rP README.md` ### Przydatne materiały + * [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/) * [Python docs Transifex: Documentation](https://python-docs-transifex-automation.readthedocs.io/) * [statystyki oglądalności](https://analytics.python.org/docs.python.org?f=contains,page,/pl/) ### Podobne projekty + * [projekty Python Packaging Authority](https://hosted.weblate.org/projects/pypa/-/pl/) * [Scientific Python Translations](https://scientific-python-translations.github.io/) * [micro:bit translation programme](https://microbit.org/translate/) From 983514c55ed24ba08e155ae77204b2427c60fb6e Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sat, 22 Aug 2026 22:03:17 +0200 Subject: [PATCH 7/8] Improve wrapping in contribute section --- README.en.md | 8 +++++--- README.md | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/README.en.md b/README.en.md index b73af2954..90938d3fa 100644 --- a/README.en.md +++ b/README.en.md @@ -49,9 +49,11 @@ Suggested priority resources for translation can be found in [issue #50](https:/ * Click the "Join this project" button. * Create an account on Transifex. * Select Polish on the project page. -* After submitting your request to join the team, introduce yourself on the [Python Polska #dokumentacja Discord channel](https://discord.gg/QB3h2Sxc). This will help us approve your request sooner. -* After joining the team, select the resource you want to improve or update. You can find more information about using Transifex -in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) or [our guide](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). +* After submitting your request to join the team, introduce yourself on the [Python Polska #dokumentacja Discord channel](https://discord.gg/QB3h2Sxc). + This will help us approve your request sooner. +* After joining the team, select the resource you want to improve or update. You can find more information about using + Transifex in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) + or [our guide](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). ### How do I check my changes locally? diff --git a/README.md b/README.md index f108a5459..d50959312 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,11 @@ projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python- * Naciśnij przycisk „Join this project”, aby dołączyć do projektu. * Utwórz konto Transifex. * Na stronie projektu wybierz język polski. -* Po wysłaniu zgłoszenia do zespołu przedstaw się na kanale [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc). Pozwoli to szybciej potwierdzić Twoje zgłoszenie. -* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. Więcej informacji o używaniu Transifeksa znajdziesz w -[jego artykułach pomocy](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) lub [w naszym przewodniku](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). +* Po wysłaniu zgłoszenia do zespołu przedstaw się na kanale [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc). + Pozwoli to szybciej potwierdzić Twoje zgłoszenie. +* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. Więcej informacji o używaniu Transifeksa + znajdziesz w [jego artykułach pomocy](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) + lub [w naszym przewodniku](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). ### Jak lokalnie sprawdzić poprawność moich zmian? From ae40359fbd671fad46daa9f67d8f7b704dcaf9a3 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sat, 22 Aug 2026 22:30:22 +0200 Subject: [PATCH 8/8] Promote getting familiar with reStructuredText syntax --- README.en.md | 6 ++++-- README.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.en.md b/README.en.md index 90938d3fa..7d5d09ea5 100644 --- a/README.en.md +++ b/README.en.md @@ -51,8 +51,10 @@ Suggested priority resources for translation can be found in [issue #50](https:/ * Select Polish on the project page. * After submitting your request to join the team, introduce yourself on the [Python Polska #dokumentacja Discord channel](https://discord.gg/QB3h2Sxc). This will help us approve your request sooner. -* After joining the team, select the resource you want to improve or update. You can find more information about using - Transifex in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) +* After joining the team, select the resource you want to improve or update. +* Get familiar with [reStructuredText syntax](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), + the documentation format. +* You can find more information about using Transifex in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) or [our guide](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). ### How do I check my changes locally? diff --git a/README.md b/README.md index d50959312..7288d87c2 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,10 @@ projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python- * Na stronie projektu wybierz język polski. * Po wysłaniu zgłoszenia do zespołu przedstaw się na kanale [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc). Pozwoli to szybciej potwierdzić Twoje zgłoszenie. -* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. Więcej informacji o używaniu Transifeksa - znajdziesz w [jego artykułach pomocy](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) +* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić lub zaktualizować. +* Zapoznaj się ze [składnią reStructuredText](https://www.sphinx-doc.org/pl/master/usage/restructuredtext/basics.html), + formatem dokumentacji. +* Więcej informacji o używaniu Transifeksa znajdziesz w [jego artykułach pomocy](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor) lub [w naszym przewodniku](https://python-docs-transifex-automation.readthedocs.io/new-translators.html). ### Jak lokalnie sprawdzić poprawność moich zmian?