diff --git a/README.en.md b/README.en.md index 295fcd2e3..6f2e44d9f 100644 --- a/README.en.md +++ b/README.en.md @@ -25,48 +25,90 @@ 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`](https://pypi.org/project/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. +* 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? + +[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 -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). +python-newest.library--turtle - Done +[##############################] (1 / 1) -**I want to start translating, but I don't know where to start!** +# Pulling files -Firstly, you can join as a translator by following the steps outlined above. +python-newest.library--turtle [pl] - Done +[##############################] (1 / 1) +``` -Then you can start by translating one of our [prioritized resources](https://github.com/python/python-docs-pl/issues/50). +Run [`sphinx-lint`](https://pypi.org/project/sphinx-lint/) to check your changes, for example: -**How to see the newest build of the documentation?** +``` +$ 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? + +[See devguide's instructions.](https://devguide.python.org/documentation/translations/translating/#how-do-i-build-a-docs-translation) + +### 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 +116,20 @@ 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/) diff --git a/README.md b/README.md index 65d44b632..7288d87c2 100644 --- a/README.md +++ b/README.md @@ -25,68 +25,117 @@ 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`](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: + +``` +$ 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 dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować. +* 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ć 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? + +[Zainstaluj Transifex CLI](https://github.com/transifex/cli#installation) i zapisz +[klucz API Transifex](https://help.transifex.com/en/articles/6248858-generating-an-api-token) do `~/.transifexrc`, aby +pobrać zmiany z Transifeksa. Pobierz zmieniony rozdział, np.: + +``` +$ tx pull --languages pl python-newest.library--turtle +# Getting info about resources + +python-newest.library--turtle - Done +[##############################] (1 / 1) -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). +# Pulling files -**Chcę pomóc w tłumaczeniu, ale nie wiem od czego zacząć!** +python-newest.library--turtle [pl] - Done +[##############################] (1 / 1) +``` -Najpierw dołącz do projektu jako tłumacz, postępując zgodnie z przewodnikiem w poprzedniej sekcji. +Uruchom [`sphinx-lint`](https://pypi.org/project/sphinx-lint/), aby sprawdzić poprawność zmian, na przykład: -Następnie możesz zacząć od tłumaczenia jednego z naszych [priorytetowych zasobów.](https://github.com/python/python-docs-pl/issues/50) +``` +$ uvx sphinx-lint library/turtle.po +No problems found. +``` -**Jak obejrzeć najnowszy build dokumentacji?** +### 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. -**Kanały komunikacji** +### Jak zbudować dokumentację? + +Aby zbudować dokumentację potrzebujesz mieć kopię repozytorium CPythona. + +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ę. + +### Kanały komunikacji * [Discord Python Polska #dokumentacja](https://discord.gg/VCyBDGH38e) * [Python Documentation Community](https://docs-community.readthedocs.io/en/latest/) * [Python Documentation Special Interest Group](https://www.python.org/community/sigs/current/doc-sig/) -**Postęp tłumaczenia** +### 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 [na licencji CC0](https://creativecommons.org/publicdomain/zero/1.0/deed.pl). 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. +Wyrażasz akceptację tej umowy, przesyłając swoją pracę do włączenia do dokumentacji. + +### Aktualizacje w repozytorium -**Aktualizacja tłumaczeń** * `./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/)