Title: Python Documentation Translation
Date: 2017-05-29

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.
