Skip to content

Commit ac1b9e9

Browse files
m-aciekm-aciek
authored
Improve README (#147)
1 parent 12f7e17 commit ac1b9e9

2 files changed

Lines changed: 137 additions & 42 deletions

File tree

‎README.en.md‎

Lines changed: 67 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -25,66 +25,112 @@ f'''[![build](https://github.com/python/python-docs-pl/actions/workflows/update-
2525

2626
*Przeczytaj to w innym języku: [polski](README.md)*
2727

28-
**I found a mistake, what do I do?**
28+
### How do I check what needs translating?
2929

30-
If you find a mistake or have a suggestion,
31-
[let us know](https://github.com/python/python-docs-pl/issues) or fix it yourself:
30+
Use the [`potodo`](https://pypi.org/project/potodo/) package. Run it in the project's root directory,
31+
for example: `uvx potodo`.
3232

33-
* Go to the website of the project [Python Documentation](https://explore.transifex.com/python-doc/python-newest/).
34-
* Click the button "Join this project", to join the Project.
33+
If you are interested in the core articles, use filtering. For example:
34+
35+
```
36+
$ uvx potodo --exclude '**/*' '!tutorial/*' '!bugs.po' '!library/functions.po'
37+
1 directory 99.68% done
38+
└── python-docs-pl/ 99.68% done
39+
├── library/ 98.61% done
40+
│ └── functions.po 99.0% translated 535/536
41+
└── tutorial/ 100.00% done
42+
```
43+
44+
Suggested priority resources for translation can be found in [issue #50](https://github.com/python/python-docs-pl/issues/50).
45+
46+
### How do I translate?
47+
48+
* Go to the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) on Transifex.
49+
* Click the "Join this project" button.
3550
* Create an account on Transifex.
36-
* On the project website pick the language Polish.
37-
* After joining the Project, pick the category you want to fix/translate.
51+
* Select Polish on the project page.
52+
* After submitting your request to join the team, introduce yourself on
53+
the [Python Polska `#dokumentacja` Discord channel](https://discord.gg/VCyBDGH38e).
54+
This will help us approve your request sooner.
55+
* After joining the team, select the resource you want to improve or update.
56+
* Get familiar with [reStructuredText syntax](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html),
57+
the documentation format.
58+
* You can find more information about using Transifex in [their help articles](https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor)
59+
or [our guide](https://python-docs-transifex-automation.readthedocs.io/new-translators.html).
60+
61+
### How do I check my changes locally?
62+
63+
[Install the Transifex CLI](https://github.com/transifex/cli#installation) and save your
64+
[Transifex API token](https://help.transifex.com/en/articles/6248858-generating-an-api-token) to `~/.transifexrc` so that you
65+
can download changes from Transifex. Download the changed chapter, for example:
66+
67+
```
68+
$ tx pull --languages pl python-newest.library--turtle
69+
# Getting info about resources
3870
39-
You can find more information about using Transifex
40-
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).
71+
python-newest.library--turtle - Done
72+
[##############################] (1 / 1)
4173
42-
**I want to start translating, but I don't know where to start!**
74+
# Pulling files
4375
44-
Firstly, you can join as a translator by following the steps outlined above.
76+
python-newest.library--turtle [pl] - Done
77+
[##############################] (1 / 1)
78+
```
4579

46-
Then you can start by translating one of our [prioritized resources](https://github.com/python/python-docs-pl/issues/50).
80+
Run [`sphinx-lint`](https://pypi.org/project/sphinx-lint/) to check your changes, for example:
4781

48-
**How to see the newest build of the documentation?**
82+
```
83+
$ uvx sphinx-lint library/turtle.po
84+
No problems found.
85+
```
86+
87+
### How do I see the latest build of the documentation?
4988

5089
Download the latest build from the list of artefacts in the latest GitHub Action (Actions Tab).
51-
Translations are pulled from Transifex around every half hour.
90+
Translations are pulled from Transifex around once an hour.
5291
The documentation at https://docs.python.org/pl/ is updated around once daily.
5392

54-
**Communication Channels**
93+
### How do I build the documentation?
94+
95+
[See devguide's instructions.](https://devguide.python.org/documentation/translations/translating/#how-do-i-build-a-docs-translation)
96+
97+
### Communication channels
5598

5699
* [Discord Python Polska #dokumentacja](https://discord.gg/QB3h2Sxc)
57100
* [Python Documentation Community](https://docs-community.readthedocs.io/)
58101
* [Python Documentation Special Interest Group](https://www.python.org/community/sigs/current/doc-sig/)
59102

60-
**Translation progress**
103+
### Translation progress
61104

62-
<img src="translation_progress_en.svg" alt="Translation progress">
105+
<img src="translation_progress_en.svg" alt="Translation progress">
63106

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

69-
**License**
112+
### License
70113

71114
By inviting you to work on a project on the Transifex platform, we offer a contract for
72115
donating your translations to the Python Software Foundation
73116
[under the CC0 license](https://creativecommons.org/publicdomain/zero/1.0/deed.pl).
74117
In return, it will be visible that you are the translator of the part you translated.
75118
You signify your acceptance of this agreement by submitting your work for inclusion in the documentation.
76119

77-
**Updating Translations**
120+
### Repository updates
121+
78122
* `./manage_translation.py recreate_tx_config`
79123
* `./manage_translation.py fetch`
80124
* `cog -rP README.en.md`
81125

82-
**Useful Materials**
126+
### Useful materials
127+
83128
* [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/)
84129
* [Python docs Transifex: Documentation](https://python-docs-transifex-automation.readthedocs.io/)
85130
* [Site Statistics](https://analytics.python.org/docs.python.org?f=contains,page,/pl/)
86131

87-
**Similar Translation Projects**
132+
### Similar projects
133+
88134
* [Projects of the Python Packaging Authority](https://hosted.weblate.org/projects/pypa/-/pl/)
89135
* [Scientific Python Translations](https://scientific-python-translations.github.io/)
90136
* [micro:bit translation programme](https://microbit.org/translate/)

‎README.md‎

Lines changed: 70 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -25,68 +25,117 @@ f'''[![build](https://github.com/python/python-docs-pl/actions/workflows/update-
2525

2626
*Read this in another language: [English](README.en.md)*
2727

28-
**Znalazłem błąd, co mam zrobić?**
28+
### Jak sprawdzić, co jest do przetłumaczenia?
2929

30-
Jeśli znalazłeś(-aś) błąd lub masz sugestię,
31-
[dodaj zgłoszenie](https://github.com/python/python-docs-pl/issues) w tym projekcie lub
32-
napraw go sam(a):
30+
Służy do tego paczka [`potodo`](https://pypi.org/project/potodo/). Wywołaj ją w głównym katalogu projektu,
31+
na przykład `uvx potodo`.
32+
33+
Jeżeli interesują cię podstawowe artykuły, użyj filtrowania. Przykład:
34+
35+
```
36+
$ uvx potodo --exclude '**/*' '!tutorial/*' '!bugs.po' '!library/functions.po'
37+
1 directory 99.68% done
38+
└── python-docs-pl/ 99.68% done
39+
├── library/ 98.61% done
40+
│ └── functions.po 99.0% translated 535/536
41+
└── tutorial/ 100.00% done
42+
```
43+
44+
Propozycje priorytetowych zasobów do tłumaczenia można znaleźć w [issue #50](https://github.com/python/python-docs-pl/issues/50).
45+
46+
### Jak tłumaczyć?
3347

3448
* Wejdź na stronę
35-
projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python-newest/).
49+
projektu [dokumentacji Pythona](https://explore.transifex.com/python-doc/python-newest/) na Transifeksie.
3650
* Naciśnij przycisk „Join this project”, aby dołączyć do projektu.
3751
* Utwórz konto Transifex.
3852
* Na stronie projektu wybierz język polski.
39-
* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić/zaktualizować.
53+
* Po wysłaniu zgłoszenia do zespołu przedstaw się na kanale [Discord Python Polska `#dokumentacja`](https://discord.gg/VCyBDGH38e).
54+
Pozwoli to szybciej potwierdzić Twoje zgłoszenie.
55+
* Po dołączeniu do zespołu wybierz zasób, który chcesz poprawić lub zaktualizować.
56+
* Zapoznaj się ze [składnią reStructuredText](https://www.sphinx-doc.org/pl/master/usage/restructuredtext/basics.html),
57+
formatem dokumentacji.
58+
* 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)
59+
lub [w naszym przewodniku](https://python-docs-transifex-automation.readthedocs.io/new-translators.html).
60+
61+
### Jak lokalnie sprawdzić poprawność moich zmian?
62+
63+
[Zainstaluj Transifex CLI](https://github.com/transifex/cli#installation) i zapisz
64+
[klucz API Transifex](https://help.transifex.com/en/articles/6248858-generating-an-api-token) do `~/.transifexrc`, aby
65+
pobrać zmiany z Transifeksa. Pobierz zmieniony rozdział, np.:
66+
67+
```
68+
$ tx pull --languages pl python-newest.library--turtle
69+
# Getting info about resources
70+
71+
python-newest.library--turtle - Done
72+
[##############################] (1 / 1)
4073
41-
Więcej informacji o używaniu Transifeksa znajdziesz w
42-
[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).
74+
# Pulling files
4375
44-
**Chcę pomóc w tłumaczeniu, ale nie wiem od czego zacząć!**
76+
python-newest.library--turtle [pl] - Done
77+
[##############################] (1 / 1)
78+
```
4579

46-
Najpierw dołącz do projektu jako tłumacz, postępując zgodnie z przewodnikiem w poprzedniej sekcji.
80+
Uruchom [`sphinx-lint`](https://pypi.org/project/sphinx-lint/), aby sprawdzić poprawność zmian, na przykład:
4781

48-
Następnie możesz zacząć od tłumaczenia jednego z naszych [priorytetowych zasobów.](https://github.com/python/python-docs-pl/issues/50)
82+
```
83+
$ uvx sphinx-lint library/turtle.po
84+
No problems found.
85+
```
4986

50-
**Jak obejrzeć najnowszy build dokumentacji?**
87+
### Jak obejrzeć najnowszy build dokumentacji?
5188

5289
Pobierz ostatnią zbudowaną dokumentację z listy artefaktów w ostatniej GitHub Action (zakładka Actions).
53-
Tłumaczenia pobierane są z Transifeksa do tego repozytorium co około pół godziny.
90+
Tłumaczenia pobierane są z Transifeksa do tego repozytorium co około godzinę.
5491
Dokumentacja na https://docs.python.org/pl/ aktualizowana jest około raz dziennie.
5592

56-
**Kanały komunikacji**
93+
### Jak zbudować dokumentację?
94+
95+
Aby zbudować dokumentację potrzebujesz mieć kopię repozytorium CPythona.
96+
97+
Zrób link symboliczny (Unix) lub kopię (Windows) zawartości projektu `python-docs-pl` w katalogu
98+
`Doc/locales/pl/LC_MESSAGES` w repozytorium CPython.
99+
100+
Następnie uruchom `make -C Doc SPHINXOPTS="-D language=pl" html` w projekcie CPython, aby zbudować dokumentację.
101+
102+
### Kanały komunikacji
57103

58104
* [Discord Python Polska #dokumentacja](https://discord.gg/VCyBDGH38e)
59105
* [Python Documentation Community](https://docs-community.readthedocs.io/en/latest/)
60106
* [Python Documentation Special Interest Group](https://www.python.org/community/sigs/current/doc-sig/)
61107

62-
**Postęp tłumaczenia**
108+
### Postęp tłumaczenia
63109

64-
<img src="translation_progress_pl.svg" alt="Postęp tłumaczenia">
110+
<img src="translation_progress_pl.svg" alt="Postęp tłumaczenia">
65111

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

71-
**Licencja**
117+
### Licencja
72118

73119
Zapraszając do współtworzenia projektu na platformie Transifex, proponujemy umowę na
74120
przekazanie twoich tłumaczeń Python Software Foundation
75121
[na licencji CC0](https://creativecommons.org/publicdomain/zero/1.0/deed.pl).
76122
W zamian będzie widoczne, że jesteś tłumaczem(-ką) części, którą przetłumaczyłeś(-łaś).
77-
Wyrażasz akceptację tej umowy przesyłając swoją pracę do włączenia do dokumentacji.
123+
Wyrażasz akceptację tej umowy, przesyłając swoją pracę do włączenia do dokumentacji.
124+
125+
### Aktualizacje w repozytorium
78126

79-
**Aktualizacja tłumaczeń**
80127
* `./manage_translation.py recreate_tx_config`
81128
* `./manage_translation.py fetch`
82129
* `cog -rP README.md`
83130

84-
**Przydatne materiały**
131+
### Przydatne materiały
132+
85133
* [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/)
86134
* [Python docs Transifex: Documentation](https://python-docs-transifex-automation.readthedocs.io/)
87135
* [statystyki oglądalności](https://analytics.python.org/docs.python.org?f=contains,page,/pl/)
88136

89-
**Podobne projekty**
137+
### Podobne projekty
138+
90139
* [projekty Python Packaging Authority](https://hosted.weblate.org/projects/pypa/-/pl/)
91140
* [Scientific Python Translations](https://scientific-python-translations.github.io/)
92141
* [micro:bit translation programme](https://microbit.org/translate/)

0 commit comments

Comments
 (0)