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

Open
m-aciek wants to merge 5 commits into
base: 3.15
Choose a base branch
from
Open

Improve README #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 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
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
82 changes: 63 additions & 19 deletions README.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,66 +25,110 @@ 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`.

@StanFromIreland StanFromIreland Aug 21, 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.

Link to potodo on PyPI?


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

@StanFromIreland StanFromIreland Aug 21, 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.

We can link to https://devguide.python.org/documentation/translations/translating/#how-do-i-build-a-docs-translation instead?


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

<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

@StanFromIreland StanFromIreland Aug 21, 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.

Please add a newline after the heading for consistency.

* `./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/)
Expand Down
79 changes: 61 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,68 +25,111 @@ 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?

[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)

Najpierw dołącz do projektu jako tłumacz, postępując zgodnie z przewodnikiem w poprzedniej sekcji.
# Pulling files

Następnie możesz zacząć od tłumaczenia jednego z naszych [priorytetowych zasobów.](https://github.com/python/python-docs-pl/issues/50)
python-newest.library--turtle [pl] - Done
[##############################] (1 / 1)
```

**Jak obejrzeć najnowszy build dokumentacji?**
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.

**Kanały komunikacji**
### Jak zbudować dokumentację?

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

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.

**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/)
Expand Down
Loading