Skip to content

Improve README #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
m-aciek merged 15 commits into from
Aug 27, 2026
Merged

Improve README #147

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
130bea7
Make README focused on new content translations
m-aciek Jul 27, 2026
2691316
Interpunctuation
m-aciek Jul 27, 2026
ad998a6
tx improv
m-aciek Jul 27, 2026
43d6848
Improve README structure and build instructions
m-aciek Aug 21, 2026
9bb722e
Port changes to English version
m-aciek Aug 21, 2026
5570480
Links to PyPI, newlines after headings, build and contribute section …
m-aciek Aug 22, 2026
983514c
Improve wrapping in contribute section
m-aciek Aug 22, 2026
ae40359
Promote getting familiar with reStructuredText syntax
m-aciek Aug 22, 2026
037dc46
Fix potodo project link
m-aciek Aug 23, 2026
2ac0299
Update README.en.md: remove superfluous backtick
m-aciek Aug 23, 2026
bf3389f
README: format channel name
m-aciek Aug 23, 2026
77fbefc
Format channel name as code, fix links
m-aciek Aug 26, 2026
0886322
add friendly-traceback project to related
m-aciek Aug 26, 2026
e705447
remove extra backtick
m-aciek Aug 26, 2026
5fb81dc
Revert adding friendly-traceback to similar projects
m-aciek Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 68 additions & 21 deletions README.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,68 +25,115 @@ 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/VCyBDGH38e).
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

<img src="translation_progress_en.svg" alt="Translation progress">
<img src="translation_progress_en.svg" alt="Translation progress">

<!---
Excludes the changelog from calculations.
Made using: https://gist.github.com/StanFromIreland/ce400e0d497018fc8e8eb6b739e0b8eb
--->

**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
[under the CC0 license](https://creativecommons.org/publicdomain/zero/1.0/deed.pl).
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
Comment thread
m-aciek marked this conversation as resolved.

* `./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/)
* [Sphinx translation](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#contributing-to-sphinx-reference-translation)
* [Localizing Django](https://docs.djangoproject.com/en/dev/internals/contributing/localizing/)
* [friendly-traceback: notes on translations](https://friendly-traceback.github.io/docs/translation_notes.html)

@StanFromIreland StanFromIreland Aug 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't fall under "Similar projects" and also doesn’t really seem relevant here for translators, as we use TX. So I suggest dropping it.

@m-aciek m-aciek Aug 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion it is similar conceptually, as it's Python-related localisation, lowers entry barrier, and can be used in education (see micro:bit; hopefully we can add turtle-translations soon here too); I'm fine to put it in a separate follow-up PR

@m-aciek m-aciek Aug 27, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed from here to limit scope

92 changes: 71 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,70 +25,120 @@ 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/VCyBDGH38e).
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

<img src="translation_progress_pl.svg" alt="Postęp tłumaczenia">
<img src="translation_progress_pl.svg" alt="Postęp tłumaczenia">

<!---
Excludes the changelog from calculations.
Made using: https://gist.github.com/StanFromIreland/ce400e0d497018fc8e8eb6b739e0b8eb
--->

**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/)
* [tłumaczenie Sphinksa](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#contributing-to-sphinx-reference-translation)
* [Localizing Django](https://docs.djangoproject.com/en/dev/internals/contributing/localizing/)
* [friendly-traceback: notes on translations](https://friendly-traceback.github.io/docs/translation_notes.html)
Loading