183 lines
7.7 KiB
Markdown
183 lines
7.7 KiB
Markdown
Title: Python Documentation Translation
|
|
|
|
This is an overview of what is done, what we're doing, and what's
|
|
needs work about the translation of Python documentation.
|
|
|
|
|
|
# Historical context
|
|
|
|
The first step to ensure every other steps are worth it was to
|
|
officialize the translations. This is now done with the [PEP
|
|
545](https://www.python.org/dev/peps/pep-0545/).
|
|
|
|
|
|
# PEP 545: TL;DR
|
|
|
|
The PEP 545 may be long to read, so here are the interesting points:
|
|
|
|
- Each translation is assigned an appropriate lowercased language tag,
|
|
with an optional region subtag (if needed), glued with a
|
|
dash, like `pt-br` or `fr`.
|
|
|
|
- Translations files are hosted on
|
|
`https://github.com/python/python-docs-{LANGUAGE_TAG}`
|
|
|
|
- Translations are hosted on
|
|
`https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/`.
|
|
|
|
|
|
# Bootstrap a new translation
|
|
|
|
To bootstrap a new translation you'll need a clone of cpython in the 3.7 (or newer) branch:
|
|
|
|
git clone https://github.com/python/cpython.git
|
|
git -C cpython checkout 3.7
|
|
|
|
And a directory for your repo, initialized for example with my Makefile:
|
|
|
|
mkdir python-docs-whatever
|
|
cd python-docs-whatever
|
|
git init
|
|
git checkout -b 3.7
|
|
wget -q https://raw.githubusercontent.com/python/python-docs-fr/3.7/Makefile
|
|
git add Makefile
|
|
git commit -m "Initial commit."
|
|
make merge
|
|
git add *.po */*.po
|
|
git commit -m "Adding po files."
|
|
|
|
|
|
# Current status
|
|
|
|
Language | Contact | Links
|
|
----------------------------------------|------------------------------------|-------------------------------------------
|
|
Arabic (ar) | Abdur-Rahmaan Janhangeer | [github][github-ar]
|
|
Bengali as spoken in Bangladesh (bn_BD) | | [tweet][tweet-bn-bd]
|
|
Bengali as spoken in India (bn_IN) | [Kushal Das](kushal) | [github][github-bn-in]
|
|
[French (fr)][fr] | [Julien Palard (mdk)][mdk] | [github][github-fr]
|
|
Hindi as spoken in India (hi_IN) | | [github][github-hi-in]
|
|
Hungarian (hu) | [Tamás Bajusz (gbtami)][gbtami] | [github][github-hu] [doc][doc-hu] [list][list-hu]
|
|
Italian (it) | | [mail][mail-it]
|
|
[Japanese (ja)][ja] | [Inada Naoki (methane)][methane] | [github][github-ja]
|
|
[Korean (ko)][ko] | | [github][github-ko]
|
|
Polish (pl) | | [mail][mail-pl]
|
|
Portuguese (pt) | Gustavo Toffo |
|
|
Portuguese as spoken in Brasil (pt-br) | [Marco Rougeth][rougeth] | [github][github-pt-br] [wiki][wiki-pt-br] [telgram][telegram-pt-br] [article][article-pt-br]
|
|
Russian (ru) | | [mail][mail-ru]
|
|
[Simplified Chinese (zh-cn)][zh-cn] | [Shengjing Zhu][shengjing] | [transifex][tx-zh-cn] [github][github-zh-cn]
|
|
Spanish (es) | Raul Cumplido | [github][github-es] [old repo][github-old-es]
|
|
[Traditional Chinese (zh-tw)][zh-tw] | 廖偉涵 Adrian Liaw | [github][github-zh-tw] [transifex][tx-zh-tw]
|
|
Turkish (tr) | | [github][github-tr]
|
|
|
|
[tweet-bn-bd]: https://twitter.com/auvipy/status/867370828408569856
|
|
[mail-pl]: https://mail.python.org/pipermail/doc-sig/2019-April/004106.html
|
|
[mail-it]: https://mail.python.org/pipermail/doc-sig/2019-April/004114.html
|
|
[mail-ru]: https://mail.python.org/pipermail/doc-sig/2019-May/004131.html
|
|
[tx-zh-cn]: https://www.transifex.com/python-doc/python-newest/language/zh_CN/
|
|
[tx-zh-tw]: https://www.transifex.com/python-tw-doc/python-36-tw
|
|
|
|
[doc-hu]: http://harp.pythonanywhere.com/python_doc/tutorial/index.html
|
|
[list-hu]: https://mail.python.org/pipermail/python-hu/
|
|
|
|
[tweet-bn-bd]: https://twitter.com/auvipy/status/867370828408569856
|
|
[mail-pl]: https://mail.python.org/pipermail/doc-sig/2019-April/004106.html
|
|
[mail-it]: https://mail.python.org/pipermail/doc-sig/2019-April/004114.html
|
|
[tx-zh-cn]: https://www.transifex.com/python-doc/python-newest/language/zh_CN/
|
|
[tx-zh-tw]: https://www.transifex.com/python-tw-doc/python-36-tw
|
|
|
|
|
|
|
|
[wiki-pt-br]: http://python.org.br/traducao
|
|
[telegram-pt-br]: https://t.me/pybr_i18n
|
|
[article-pt-br]: http://rgth.co/blog/python-ptbr-cenario-atual
|
|
|
|
|
|
[github-ar]: https://github.com/Abdur-rahmaanJ/py-docs-ar
|
|
[github-hu]: https://github.com/python/python-docs-hu/
|
|
[github-tr]: https://github.com/alaeddingurel/python-docs-tr
|
|
[github-es]: https://github.com/raulcd/python-docs.es/
|
|
[github-old-es]: https://github.com/PyAr/tutorial/
|
|
[github-ja]: https://github.com/python/python-docs-ja/
|
|
[github-fr]: https://github.com/python/python-docs-fr/
|
|
[github-ko]: https://github.com/python/python-docs-ko/
|
|
[github-bn-in]: https://github.com/python/python-docs-bn-in
|
|
[github-hi-in]: https://github.com/CuriousLearner/python-docs-hi-in
|
|
[github-pt-br]: https://github.com/python/python-docs-pt-br/
|
|
[github-zh-tw]: https://github.com/python/python-docs-zh-tw/
|
|
[github-zh-cn]: https://github.com/python/python-docs-zh-cn/
|
|
|
|
[methane]: https://bugs.python.org/user10371
|
|
[mdk]: https://bugs.python.org/user23063
|
|
[shengjing]: https://bugs.python.org/user24811
|
|
[rougeth]: https://mail.python.org/pipermail/doc-sig/2017-June/003975.html
|
|
[gbtami]: http://bugs.python.org/user25857
|
|
[kushal]: http://bugs.python.org/user16382
|
|
|
|
[ja]: https://docs.python.org/ja/
|
|
[fr]: https://docs.python.org/fr/
|
|
[ko]: https://docs.python.org/ko/
|
|
[zh-cn]: https://docs.python.org/zh-cn/
|
|
[zh-tw]: https://docs.python.org/zh-tw/
|
|
|
|
|
|
|
|
# FAQ
|
|
|
|
## I want to translate, where do I start?
|
|
|
|
Step one may be to subscribe to the
|
|
[Doc-SIG](https://mail.python.org/mailman/listinfo/doc-sig) mailing
|
|
list, and maybe join the `#python-doc` channel on Libera.Chat.
|
|
|
|
You should present yourself on the doc-sig mailing list explain what you have
|
|
and from here we'll help you through the steps of the PEP.
|
|
|
|
|
|
## How a coordinator is elected?
|
|
|
|
There is no election per se, but some basic rules:
|
|
|
|
- Coordinator requests are to be public on doc-sig mailing list.
|
|
- If the given language have a native core dev, the core dev have its
|
|
word on the choice.
|
|
- If one want to become coordinator for its native language, and
|
|
shows motivation by translating and building a community, it will
|
|
be named coordinator.
|
|
- In case of concurrency between two persons, no one will sort this
|
|
out for you, it's open to you to organize a local election or
|
|
whatever needed to sort this out.
|
|
- In case a coordinator become inactive or unreachable for a long
|
|
period of time, someone else can ask for a takeover on doc-sig.
|
|
|
|
|
|
|
|
|
|
## The entry for my translation is missing/not up to date on this page
|
|
|
|
Tell me, I'm `mdk` on `#python-doc` and I'm Julien Palard on the
|
|
mailing lists.
|
|
|
|
|
|
## I have a translation, but not on git, what should I do?
|
|
|
|
Just ask for help on the doc-sig mailing list and our python-fu,
|
|
git-fu and bash-fu combined will help you create an appropriate
|
|
repository. If you use a tool like transifex don't worry keeping them
|
|
in sync is not that hard.
|
|
|
|
|
|
## My git hierarchy does not match yours, can I keep it?
|
|
|
|
No, inside the ``github.com/python`` organization we'll all have the
|
|
exact same hierarchy so bots will be able to build all of our
|
|
translations. So you may have to convert from one hierarchy to
|
|
another. Ask for help on the doc-sig mailing list if you're not sure
|
|
on how to do it.
|
|
|
|
|
|
## What hierarchy should I use in my github repository?
|
|
|
|
As for every projects we have a *branch* per version, we store ``po``
|
|
files in the root of the repository using the ``gettext_compact=0``
|
|
style.
|