8000 Update `translations/coordinating.rst` (GH-1587) · python/devguide@b0aefe9 · GitHub
[go: up one dir, main page]
Skip to content

Commit b0aefe9

Browse files
StanFromIrelandStanFromIreland
authored
Update translations/coordinating.rst (GH-1587)
1 parent 25cb613 commit b0aefe9

File tree

5 files changed

+391
-70
lines changed

5 files changed

+391
-70
lines changed

‎contrib/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ major section at the top of each column.]*
7575
* :ref:`documenting`
7676
* :ref:`style-guide`
7777
* :ref:`rst-primer`
78-
* :doc:`documentation/translations`
78+
* :ref:`translating`
7979
* :ref:`devguide`
8080
-
8181
* :ref:`setup`

‎documentation/translations/coordinating.rst‎

Lines changed: 192 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -3,79 +3,186 @@ Coordinating
33
============
44

55
Information about the Python documentation translation processes is
6-
found in this devguide and :PEP:`545`.
7-
Translations are built by `docsbuild-scripts
8-
<https://github.com/python/docsbuild-scripts/>`__ and hosted on
9-
docs.python.org. Translations
10-
are overseen by the `Editorial Board <EB_>`_
6+
found on this page and in :PEP:`545`. Translations are overseen by the
7+
`Editorial Board <EB_>`_.
8+
9+
.. _translation-help:
10+
11+
Communication/help channels
12+
===========================
13+
14+
Discussions about translations occur on the Python Docs Discord
15+
`#translations channel <https://discord.gg/h3qDwgyzga>`_, `translation
16+
mailing list <translation_ml_>`_, and the
17+
`translations category <trans_disc_>`_ of the Python Discourse.
18+
19+
For administrative issues, ping ``@python/editorial-board``.
20+
1121

1222
Starting a new translation
1323
==========================
1424

15-
First subscribe to the `translation mailing list <translation_ml_>`_,
16-
and introduce yourself and the translation you're starting.
25+
Coordination is not a one-off task, it is a long-term commitment. Before
26+
you start your translation, carefully consider if you will be able to commit
27+
to this.
28+
Every coordinator should be familiar with translating: see :ref:`translating`.
29+
30+
The following sections will guide you through setting up your translation.
31+
If you have any questions or need help, ask in one of the
32+
:ref:`help channels <translation-help>`.
33+
34+
35+
Announcement
36+
------------
37+
38+
Post an announcement introducing yourself and the translation you're
39+
starting on `Discourse <trans_disc>`_. Also join the other communication
40+
channels, if possible.
41+
42+
43+
Coordination team
44+
-----------------
45+
46+
Each translation team will decide on the number of coordinators.
47+
While initially one person is fine, we recommend expanding to having two or
48+
three coordinators. You can find more on choosing coordinators in the FAQ
49+
section on this page.
50+
51+
52+
Translation team
53+
----------------
54+
55+
.. figure:: translator-workload.svg
56+
:class: invert-in-dark-mode
57+
:align: center
58+
:alt: An exaggerated chart showing that individual translator workload
59+
decreases with the number of translators.
60+
61+
62+
Gather people to translate with you. You can't do it alone.
63+
Update :ref:`this table <translation-coordinators>` via a PR on the devguide
64+
to make your translation easier to find. In the entry you can also include links
65+
to guides or other resources for translators.
66+
67+
68+
Repository
69+
----------
70+
71+
To start your translation create a GitHub repository, under any
72+
account, with the correct Git hierarchy and folder structure. This can be done
73+
in several ways, and depends on what translation process you plan to use.
74+
75+
Each translation is assigned an appropriate lowercase
76+
`IETF language tag <https://datatracker.ietf.org/doc/html/rfc5646.html>`_.
77+
The tag may have an optional subtag, joined with a dash.
78+
For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese).
79+
The repository name is then: ``python-docs-TAG``
80+
81+
The name of each branch should be the Python version it holds translations
82+
for, for example, ``3.14``. The files should be structured like the source files
83+
in `CPython/Doc <https://github.com/python/cpython/tree/main/Doc>`_.
84+
A correctly set up repository looks like this:
85+
`python-docs-pl <https://github.com/python/python-docs-pl/>`_
86+
87+
Below, the recommended ways for starting your repository are described. You can
88+
choose another way if you like; it’s up to you.
89+
90+
91+
Cookiecutter/bootstrapper
92+
~~~~~~~~~~~~~~~~~~~~~~~~~
1793

18-
Then you can bootstrap your new translation by using the `cookiecutter
94+
You can bootstrap your new translation by using the `cookiecutter
1995
<https://github.com/python-docs-translations/python-docs-cookiecutter>`__ or
2096
`bootstrapper <https://github.com/python-docs-translations/python-docs-bootstrapper>`__.
21-
You can also start your translation using `Transifex <https://explore.transifex.com/python-doc/python-newest/>`_
22-
following this `guide <https://python-docs-transifex-automation.readthedocs.io/commands.html>`_.
97+
The repository can then be used with a pull-request based translation process.
2398

24-
The important steps look like this:
2599

26-
- Create the GitHub repo (any account) with the correct hierarchy by using one
27-
of the bootstrappers or Transifex.
28-
- Gather people to help you translate. You can't do it alone.
29-
- You can use any tool to translate, as long as you can synchronize with Git.
30-
Some use Transifex, and some use only GitHub. You can choose another
31-
way if you like; it's up to you.
32-
- Update :doc:`this page <translating>` to reflect your work and progress, either via a
33-
PR or by asking on the `translation mailing list <translation_ml_>`_.
34-
- When ``bugs``, ``tutorial``, and ``library/functions`` are 100%
35-
completed, ask on the `translation mailing list <translation_ml_>`_ for
36-
your language to be added in the language switcher on docs.python.org.
100+
Translation platform
101+
~~~~~~~~~~~~~~~~~~~~
37102

103+
You can also start your translation using
104+
`Transifex <https://explore.transifex.com/python-doc/python-newest/>`_.
105+
This will allow you to translate via the web interface, and to use shared
106+
automatically updated source files.
38107

39-
How to get help
40-
===============
108+
This is best done with a workflow that periodically checks for translations.
109+
An example with instructions can be found in the
110+
`python-docs-tx-automations documentation <https://python-docs-transifex-automation.readthedocs.io/workflows.html>`__.
111+
An in-depth guide for manually doing this can also be found
112+
in the same documentation's
113+
`commands page <https://python-docs-transifex-automation.readthedocs.io/commands.html>`__.
41114

42-
Discussions about translations occur on the Python Docs Discord
43-
`#translations channel <https://discord.gg/h3qDwgyzga>`_, `translation
44-
mailing list <translation_ml_>`_, and the
45-
`translations category <https://discuss.python.org/c/documentation/translations/>`_
46-
of the Python Discourse.
115+
To be added as coordinators on Transifex for your language, open an issue
116+
in the `tracker <https://github.com/python-docs-translations/transifex-automations/issues>`__.
117+
118+
119+
Glossary
120+
--------
121+
122+
Each translation team should have a way to store translations of terms to ensure
123+
consistency. This is often done with a glossary. More information about the use
124+
of glossaries can be found in the :ref:`translation-style-guide`.
125+
126+
127+
Moving the repo to the ``python`` org
128+
-------------------------------------
129+
130+
This will allow you to plug your translation into docsbuild-scripts_, and it
131+
will be found at `` A3E2 docs.python.org/LANG/``, but not in the switcher.
132+
133+
.. TODO Give a general milestone when this will be done.
134+
135+
Adding to the language switcher
136+
-------------------------------
137+
138+
.. TODO Specify branch: https://github.com/python/devguide/issues/1586
139+
140+
Once the following resources have been fully translated:
141+
142+
- ``bugs.po``, with proper links to the language repository issue tracker
143+
- all files in the ``tutorial/`` folder
144+
- ``library/functions.po``, the page documenting builtins
145+
146+
the translation can be added to the language switcher. This can be done with a
147+
pull request to docsbuild-scripts_, like `this commit <https://github.com/python/docsbuild-scripts/commit/e4a8aff9772738a63d0945042777d18c3d926930>`__
148+
if your translation was previously built but not in the switcher, or like
149+
`this commit <https://github.com/python/docsbuild-scripts/commit/a601ce67c6c2f3be7fde3376d3e5d3851f19950b>`__
150+
if this is it's initial addition.
47151

48152

49153
PEP 545 summary
50154
===============
51155

52156
Here are the essential points of :PEP:`545`:
53157

54-
- Each translation is assigned an appropriate lowercased language tag,
55-
with an optional region subtag, and joined with a dash, like
56-
``pt-br`` or ``fr``.
158+
- Each translation is assigned an appropriate lowercase
159+
`IETF language tag <https://datatracker.ietf.org/doc/html/rfc5646.html>`_.
160+
The tag may have an optional region subtag, joined with a dash.
161+
For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese).
57162

58-
- Each translation is under CC0 and marked as such in the README (as in
59-
the cookiecutter).
163+
- Each translation is under CC0 and is marked as such in the README.
60164

61-
- Translation files are hosted on
62-
``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not
63-
mandatory to start a translation, but mandatory to land on
64-
``docs.python.org``).
165+
- Translation files are hosted in repositories under the Python org:
166+
``https://github.com/python/python-docs-{LANGUAGE_TAG}``
65167

66-
- Translations having completed ``tutorial/``, ``library/stdtypes``
67-
and ``library/functions`` are hosted on
68-
``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``.
168+
- Translations having completed ``bugs``, ``tutorial/``
169+
and ``library/functions`` are added to the language switcher.
69170

70171

71-
Transifex
72-
=========
172+
Translating Sphinx
173+
==================
73174

74-
If you need help from a Transifex administrator, open an issue on the
75-
`tracker <https://github.com/python-docs-translations/transifex-automations/issues>`_.
175+
Some messages that appear in the docs must be translated in the
176+
`Sphinx project <https://www.sphinx-doc.org/en/master/internals/contributing.html#translations>`__
177+
(`sphinx-doc on Transifex <https://app.transifex.com/sphinx-doc/>`__) or in
178+
the `python-docs-theme <https://github.com/python/python-docs-theme>`_
179+
(currently this is not possible; see this
180+
`issue <https://github.com/python/python-docs-theme/issues/194>`__).
181+
Coordinators should direct some translators there, so that the documentation
182+
is fully translated.
76183

77184

78-
Coordinating FAQ
185+
Coordination FAQ
79186
================
80187

81188
Are there tools to help in managing the repo?
@@ -98,12 +205,26 @@ More related tools and projects can be found in the
98205

99206
__ https://github.com/python-docs-translations
100207

101-
How is a coordinator elected?
102-
-----------------------------
208+
209+
How should I test my translation?
210+
---------------------------------
211+
212+
Testing should ideally be set up in your repository, and will help catch errors
213+
early and ensure translation quality. Testing generally consists of building, and
214+
linting with :pypi:`sphinx-lint`.
215+
216+
See `this documentation <https://python-docs-transifex-automation.readthedocs.io/workflows.html#test-build-workflow>`_
217+
for sample workflows with usage guides.
218+
219+
The `dashboard <https://python-docs-translations.github.io/dashboard/metadata.html>`_
220+
also tests translations and uploads error logs.
221+
222+
223+
How is a coordination team chosen?
224+
----------------------------------
103225

104226
Each translation team will decide on the number of coordinators.
105227
We recommend two or three coordinators, though you may begin with one.
106-
Here are some general suggestions.
107228

108229
- Coordinator requests are to be public on the `translation mailing list <translation_ml_>`_.
109230
- If the given language has a native core team member, they have input
@@ -114,25 +235,28 @@ Here are some general suggestions.
114235
- We expect the local community to self-organize coordinators and contributors.
115236
If you have questions, please ask on the mailing list or Discourse.
116237
- If a coordinator becomes inactive or unreachable for a long
117-
period of time, someone else can ask to be added as a primary coordinator on the `translation mailing list <translation_ml_>`_.
118-
As a community resource, we aim to keep translations up to date with active contributors, including coordinators.
238+
period of time, someone else can ask to be added as a primary coordinator on
239+
the `translation mailing list <translation_ml_>`_.
240+
As a community resource, we aim to keep translations up to date with active
241+
contributors, including coordinators.
242+
119243

120244
I have a translation, but it's not in Git. What should I do?
121245
------------------------------------------------------------
122246

123-
You can ask for help on the `translation mailing list <translation_ml_>`_, and
124-
the team will help you create an appropriate repository. You can still use tools like transifex,
125-
if you like.
247+
You can ask for help in one of the :ref:`translation-help`, and
248+
the team will help you create an appropriate repository. You can still use tools
249+
like Transifex, if you like.
126250

127251

128252
My Git hierarchy does not match yours. Can I keep it?
129253
-----------------------------------------------------
130254

131-
No, inside the ``github.com/python`` organization we’ll all have the
255+
No, inside the ``github.com/python`` organization all repositories must have the
132256
exact same hierarchy so bots will be able to build all of our
133-
translations. So you may have to convert from one hierarchy to another.
134-
Ask for help on the `translation mailing list <translation_ml_>`_ if you’re
135-
not sure on how to do it.
257+
translations. So, you may have to convert from one hierarchy to another.
258+
Ask for help in one of the :ref:`translation-help` if you’re not sure on how to
259+
do it.
136260

137261

138262
What hierarchy should I use in my GitHub repository?
@@ -143,9 +267,6 @@ files in the root of the repository using the ``gettext_compact=0``
143267
style.
144268

145269

146-
.. XXX Explain necessary folder structure
147-
148-
149270
Which version of the Python documentation should be translated?
150271
---------------------------------------------------------------
151272

@@ -156,8 +277,14 @@ propagate your translation from one branch to another using :pypi:`pomerge`.
156277
The entry for my translation is missing or not up to date
157278
---------------------------------------------------------
158279

159-
Ask on the `translation mailing list <translation_ml_>`_, or better, make a PR
160-
on the `devguide <https://github.com/python/devguide/>`__.
280+
Make a PR on the `devguide <https://github.com/python/devguide/>`__ to update it.
281+
282+
283+
How are translations built?
284+
---------------------------
285+
286+
Translations are built by `docsbuild-scripts <https://github.com/python/docsbuild-scripts/>`__
287+
and hosted on docs.python.org.
161288

162289

163290
Is there a Weblate instance we can translate on?
@@ -170,3 +297,5 @@ for updates.
170297

171298
.. _EB: https://python.github.io/editorial-board/
172299
.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/
300+
.. _trans_disc: https://discuss.python.org/c/documentation/translations/
301+
.. _docsbuild-scripts: https://github.com/python/docsbuild-scripts

‎documentation/translations/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Translations
33
============
44

55
.. toctree::
6-
:maxdepth: 3
6+
:maxdepth: 4
77

88
translating
99
coordinating

‎documentation/translations/translating.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ in production and can be found in the language switcher; others are works in
1111
progress. To get started read your repository's contributing guide, which is
1212
generally the ``README`` file, and this page.
1313
If your language isn’t listed below, feel free to start the translation!
14-
See :doc:`coordinating` guide to get started.
14+
See :doc:`coordination <coordinating>` to get started.
1515

1616
For more details about translations and their progress, see `the dashboard
1717
<https://python-docs-translations.github.io/dashboard/>`__.
@@ -126,12 +126,13 @@ General discussions about translations occur on the Python Docs Discord
126126
mailing list <translation_ml_>`_, and the `translations category <_discourse>`_
127127
of the Python Discourse.
128128

129+
.. _translation-style-guide:
129130

130131
Style guide
131132
===========
132133

133134
Before translating, you should familiarize yourself with the general
134-
documentation :doc:`style guide<../style-guide>`. Some translation-specific
135+
documentation :doc:`style guide <../style-guide>`. Some translation-specific
135136
guidelines are explained below.
136137

137138

@@ -157,7 +158,7 @@ The Python docs contain many roles (``:role:`target```) that link to other parts
157158
of the documentation.
158159
Do not translate reStructuredText roles targets, such as ``:func:`print``` or
159160
``:ref:`some-section``` because it will break the link.
160-
If alternate text (``:role:`text <target>``` is provided, it generally
161+
If alternate text (``:role:`text <target>```) is provided, it generally
161162
should be translated. You can also introduce alternate text for translation if
162163
the target is not a name or term.
163164

@@ -279,8 +280,8 @@ The coordination team for my language is inactive, what do I do?
279280
----------------------------------------------------------------
280281

281282
If you would like to coordinate, open a pull request in the
282-
`devguide <https://github.com/python/devguide>`_ adding yourself, and ping
283-
``@python/editorial-board``.
283+
`devguide <https://github.com/python/devguide>`_ adding yourself to the table
284+
at the top of this page, and ping ``@python/editorial-board``.
284285

285286

286287
.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/

0 commit comments

Comments
 (0)
0