Skip to content

Commit 6c9018f

Browse files
AA-Turnerezio-melotti
AA-Turner
authored and
ezio-melotti
committed
Split out translating
1 parent 6d054fd commit 6c9018f

File tree

3 files changed

+260
-250
lines changed

3 files changed

+260
-250
lines changed

‎documentation/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ Documentation
99
help-documenting
1010
style-guide
1111
markup
12+
translating

‎documentation/start-documenting.rst

Lines changed: 6 additions & 250 deletions
Original file line numberDiff line numberDiff line change
@@ -134,265 +134,21 @@ Sphinx_, blurb_ and python-docs-theme_ packages from PyPI)::
134134
where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
135135
see the make targets above).
136136

137-
.. _translating:
138-
139-
Translating
140-
===========
141-
142-
Python documentation translations are governed by :PEP:`545`.
143-
They are built by `docsbuild-scripts
144-
<https://github.com/python/docsbuild-scripts/>`__ and hosted on
145-
docs.python.org. There are several documentation translations already
146-
in production; others are works in progress.
147-
148-
+-----------------+-------------------------------+----------------------------+
149-
| Language | Contact | Links |
150-
+=================+===============================+============================+
151-
| Arabic (ar) | `Abdur-Rahmaan Janhangeer | `GitHub <github_ar_>`_ |
152-
| | <gh_osdotsystem_>`_ | |
153-
+-----------------+-------------------------------+----------------------------+
154-
| Bengali as | `Kushal Das <gh_kushal_>`_ | `GitHub <github_bn_in_>`_ |
155-
| spoken in | | |
156-
| India (bn_IN) | | |
157-
+-----------------+-------------------------------+----------------------------+
158-
| French (fr) | `Julien Palard (@JulienPalard)| `GitHub <github_fr_>`_ |
159-
| | <gh_mdk_>`_ | |
160-
+-----------------+-------------------------------+----------------------------+
161-
| Hindi as spoken | | `GitHub <github_hi_in_>`_ |
162-
| in India (hi_IN)| | |
163-
+-----------------+-------------------------------+----------------------------+
164-
| Hungarian (hu) | `Tamás Bajusz (@gbtami) | `GitHub <github_hu_>`_ |
165-
| | <gh_gbtami_>`_ | `Mailing List <list_hu_>`_ |
166-
+-----------------+-------------------------------+----------------------------+
167-
| Indonesian (id) | `Oon Arfiandwi <gh_oonid_>`_ | `GitHub <github_id_>`_ |
168-
+-----------------+-------------------------------+----------------------------+
169-
| Italian (it) | | `mail <mail_it_>`_ |
170-
+-----------------+-------------------------------+----------------------------+
171-
| Japanese (ja) | `Kinebuchi Tomohiko | `GitHub <github_ja_>`_ |
172-
| | (@cocoatomo) <gh_cocoatomo_>`_| `Doc <doc_ja_>`_ |
173-
+-----------------+-------------------------------+----------------------------+
174-
| Korean (ko) | | `GitHub <github_ko_>`_ |
175-
| | | `Doc <doc_ko_>`_ |
176-
+-----------------+-------------------------------+----------------------------+
177-
| Marathi (mr) | `Sanket Garade | `GitHub <github_mr_>`_ |
178-
| | <email_garade_>`_ | |
179-
+-----------------+-------------------------------+----------------------------+
180-
| Lithuanian (lt) | | `mail <mail_lt_>`_ |
181-
+-----------------+-------------------------------+----------------------------+
182-
| Persian (fa) | `Komeil Parseh (@mmdbalkhi) | `GitHub <github_fa_>`_ |
183-
| | <gh_mmdbalkhi_>`_ | |
184-
+-----------------+-------------------------------+----------------------------+
185-
| Polish (pl) | | `GitHub <github_pl_>`_ |
186-
| | | `Translations <tx_pl_>`_ |
187-
| | | `Doc <doc_pl_>`_ |
188-
| | | `mail <mail_pl_>`_ |
189-
+-----------------+-------------------------------+----------------------------+
190-
| Portuguese (pt) | Gustavo Toffo | |
191-
+-----------------+-------------------------------+----------------------------+
192-
| Portuguese | Marco Rougeth | `GitHub <github_pt_br_>`_ |
193-
| as spoken | | `Wiki <wiki_pt_br_>`_ |
194-
| in Brasil | | `Telegram <chat_pt_br_>`_ |
195-
| (pt-br) | | `article <article_pt_br_>`_|
196-
+-----------------+-------------------------------+----------------------------+
197-
| Russian (ru) | | `mail <mail_ru_>`_ |
198-
+-----------------+-------------------------------+----------------------------+
199-
| Simplified | `Shengjing Zhu <gh_zhsj_>`_ | `Transifex <tx_zh_cn_>`_ |
200-
| Chinese | | `GitHub <github_zh_cn_>`_ |
201-
| (zh-cn) | | `Doc <doc_zh_cn_>`_ |
202-
+-----------------+-------------------------------+----------------------------+
203-
| Spanish (es) | Raúl Cumplido | `GitHub <github_es_>`_ |
204-
+-----------------+-------------------------------+----------------------------+
205-
| Traditional | `王威翔 Matt Wang | `GitHub <github_zh_tw_>`_ |
206-
| Chinese | <gh_mattwang44_>`_, | `Doc <doc_zh_tw_>`_ |
207-
| (zh-tw) | Josix Wang | |
208-
+-----------------+-------------------------------+----------------------------+
209-
| Turkish (tr) | `Ege Akman (@egeakman) | `GitHub <github_tr_>`_ |
210-
| | <email_egeakman_>`_ | |
211-
+-----------------+-------------------------------+----------------------------+
212-
213-
.. _article_pt_br: https://rgth.co/blog/python-ptbr-cenario-atual/
214-
.. _gh_cocoatomo: https://github.com/cocoatomo
215-
.. _gh_gbtami: https://github.com/gbtami
216-
.. _gh_kushal: https://github.com/Kushal997-das
217-
.. _gh_mdk: https://github.com/JulienPalard
218-
.. _gh_mmdbalkhi: https://github.com/mmdbalkhi
219-
.. _gh_oonid: https://github.com/oonid
220-
.. _gh_osdotsystem: https://github.com/Abdur-rahmaanJ
221-
.. _gh_zhsj: https://github.com/zhsj
222-
.. _gh_mattwang44: https://github.com/mattwang44
223-
.. _email_egeakman: mailto:egeakmanegeakman@hotmail.com
224-
.. _email_garade: mailto:garade@pm.me
225-
.. _chat_pt_br: https://t.me/pybr_i18n
226-
.. _doc_ja: https://docs.python.org/ja/
227-
.. _doc_ko: https://docs.python.org/ko/
228-
.. _doc_pl: https://docs.python.org/pl/
229-
.. _doc_zh_cn: https://docs.python.org/zh-cn/
230-
.. _doc_zh_tw: https://docs.python.org/zh-tw/
231-
.. _github_ar: https://github.com/Abdur-rahmaanJ/python-docs-ar
232-
.. _github_bn_in: https://github.com/python/python-docs-bn-in
233-
.. _github_es: https://github.com/python/python-docs-es
234-
.. _github_fa: https://github.com/mmdbalkhi/python-docs-fa
235-
.. _github_fr: https://github.com/python/python-docs-fr
236-
.. _github_hi_in: https://github.com/CuriousLearner/python-docs-hi-in
237-
.. _github_hu: https://github.com/python/python-docs-hu
238-
.. _github_id: https://github.com/python/python-docs-id
239-
.. _github_ja: https://github.com/python/python-docs-ja
240-
.. _github_ko: https://github.com/python/python-docs-ko
241-
.. _github_mr: https://github.com/sanketgarade/python-doc-mr
242-
.. _github_pl: https://github.com/python/python-docs-pl
243-
.. _github_pt_br: https://github.com/python/python-docs-pt-br
244-
.. _github_tr: https://github.com/python-docs-tr/python-docs-tr
245-
.. _github_zh_cn: https://github.com/python/python-docs-zh-cn
246-
.. _github_zh_tw: https://github.com/python/python-docs-zh-tw
247-
.. _list_hu: https://mail.python.org/pipermail/python-hu
248-
.. _mail_it: https://mail.python.org/pipermail/doc-sig/2019-April/004114.html
249-
.. _mail_lt: https://mail.python.org/pipermail/doc-sig/2019-July/004138.html
250-
.. _mail_pl: https://mail.python.org/pipermail/doc-sig/2019-April/004106.html
251-
.. _mail_ru: https://mail.python.org/pipermail/doc-sig/2019-May/004131.html
252-
.. _tx_pl: https://www.transifex.com/python-doc/python-newest/
253-
.. _tx_zh_cn: https://www.transifex.com/python-doc/python-newest/
254-
.. _wiki_pt_br: https://python.org.br/traducao/
255-
256-
Starting a new translation
257-
--------------------------
258-
259-
First subscribe to the `translation mailing list <translation_ml_>`_,
260-
and introduce yourself and the translation you're starting. Translations
261-
fall under the aegis of the `PSF Translation Workgroup <translation_wg_>`_
262-
263-
Then you can bootstrap your new translation by using our `cookiecutter
264-
<https://github.com/JulienPalard/python-docs-cookiecutter>`__.
265-
266-
The important steps look like this:
267-
268-
- Create the GitHub repo (anywhere) with the right hierarchy (using the
269-
cookiecutter).
270-
- Gather people to help you translate. You can't do it alone.
271-
- You can use any tool to translate, as long as you can synchronize with git.
272-
Some use Transifex, and some use only GitHub. You can choose another
273-
way if you like; it's up to you.
274-
- Ensure we update this page to reflect your work and progress, either via a
275-
PR or by asking on the `translation mailing list <translation_ml_>`_.
276-
- When ``bugs.html``, ``tutorial``, and ``library/functions`` are 100%
277-
completed, ask on the `translation mailing list <translation_ml_>`_ for
278-
your language to be added in the language picker on docs.python.org.
279-
280-
281-
PEP 545 summary:
282-
----------------
283-
284-
Here are the essential points of :PEP:`545`:
285-
286-
- Each translation is assigned an appropriate lowercased language tag,
287-
with an optional region subtag, and joined with a dash, like
288-
``pt-br`` or ``fr``.
289-
290-
- Each translation is under CC0 and marked as such in the README (as in
291-
the cookiecutter).
292-
293-
- Translation files are hosted on
294-
``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not
295-
mandatory to start a translation, but mandatory to land on
296-
``docs.python.org``).
297-
298-
- Translations having completed ``tutorial/``, ``library/stdtypes``
299-
and ``library/functions`` are hosted on
300-
``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``.
301-
302-
303-
How to get help
304-
---------------
305-
306-
Discussions about translations occur on the `translation mailing list <translation_ml_>`_,
307-
and there's a `Libera.Chat IRC <https://libera.chat/>`_ channel,
308-
``#python-doc``.
309-
310-
311-
Translation FAQ
312-
---------------
313-
314-
Which version of the Python documentation should be translated?
315-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
316-
317-
Consensus is to work on current stable. You can then propagate your
318-
translation from one branch to another using `pomerge
319-
<https://pypi.org/project/pomerge/>`__.
320-
321-
322-
Are there some tools to help in managing the repo?
323-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
324-
325-
Here's what we're using:
326-
327-
- `pomerge <https://pypi.org/project/pomerge/>`__ to propagate translations
328-
from one file to others.
329-
- `pospell <https://pypi.org/project/pospell/>`__ to check for typos in ``.po`` files.
330-
- `powrap <https://pypi.org/project/powrap/>`__ to rewrap the ``.po`` files
331-
before committing. This helps keep git diffs short.
332-
- `potodo <https://pypi.org/project/potodo/>`__ to list what needs to be translated.
333-
334-
335-
How is a coordinator elected?
336-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
337-
338-
There is no election; each translation has to sort this out. Here are some suggestions.
339-
340-
- Coordinator requests are to be public on the `translation mailing list <translation_ml_>`_.
341-
- If the given language has a native core dev, the core dev has their
342-
say on the choice.
343-
- Anyone who wants to become coordinator for their native language and shows
344-
motivation by translating and building a community will be named
345-
coordinator.
346-
- In case of concurrency between two persons, no one will sort this out
347-
for you. It is up to you two to organize a local election or whatever is
348-
needed to sort this out.
349-
- If a coordinator becomes inactive or unreachable for a long
350-
period of time, someone else can ask for a takeover on the `translation mailing list <translation_ml_>`_.
351-
352-
353-
The entry for my translation is missing/not up to date on this page
354-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
355-
356-
Ask on the `translation mailing list <translation_ml_>`_, or better, make a PR on the `devguide
357-
<https://github.com/python/devguide/>`__.
358-
359-
360-
I have a translation, but it's not in git. What should I do?
361-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
362-
363-
You can ask for help on the `translation mailing list <translation_ml_>`_, and
364-
the team will help you create an appropriate repository. You can still use tools like transifex,
365-
if you like.
366-
367-
368-
My git hierarchy does not match yours. Can I keep it?
369-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
370-
371-
No, inside the ``github.com/python`` organization we’ll all have the
372-
exact same hierarchy so bots will be able to build all of our
373-
translations. So you may have to convert from one hierarchy to another.
374-
Ask for help on the `translation mailing list <translation_ml_>`_ if you’re
375-
not sure on how to do it.
376-
377-
378-
What hierarchy should I use in my GitHub repository?
379-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
380-
381-
As for every project, we have a *branch* per version. We store ``.po``
382-
files in the root of the repository using the ``gettext_compact=0``
383-
style.
384-
385137

386138
.. _docutils: https://docutils.sourceforge.io/
387139
.. _python-docs-theme: https://pypi.org/project/python-docs-theme/
388140
.. _Sphinx: https://www.sphinx-doc.org/
389141
.. _virtualenv: https://virtualenv.pypa.io/
390142
.. _blurb: https://pypi.org/project/blurb/
391-
.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter
392-
.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/
393143

394144

395145
Style Guide
396146
===========
397147

398148
Moved to :doc:`style-guide`
149+
150+
151+
Translating
152+
===========
153+
154+
Moved to :doc:`translating`

0 commit comments

Comments
 (0)