Skip to content

Commit c485c9d

Browse files
StanFromIrelandStanFromIreland
committed
Big Split
1 parent 48b8d07 commit c485c9d

File tree

5 files changed

+134
-116
lines changed

5 files changed

+134
-116
lines changed

‎conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,10 @@
127127
# Documentation
128128
"docquality.rst": "documentation/help-documenting.rst",
129129
"documenting.rst": "documentation/start-documenting.rst",
130+
# Translating
131+
"documentation/translating.rst": "documentation/translations/translating.rst",
132+
"translating.rst": "documentation/translations/translating.rst",
133+
"coordinating.rst": "documentation/translations/coordinating.rst",
130134
# Getting Started
131135
"fixingissues.rst": "getting-started/fixing-issues.rst",
132136
"help.rst": "getting-started/getting-help.rst",

‎documentation/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,5 @@ Documentation
99
help-documenting
1010
style-guide
1111
markup
12-
translating
12+
translations/index
1313
devguide

‎documentation/translations/coordinating.rst‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
============
2+
Coordinating
3+
============
4+
5+
Starting a new translation
6+
==========================
7+
8+
First subscribe to the `translation mailing list <translation_ml_>`_,
9+
and introduce yourself and the translation you're starting. Translations
10+
fall under the aegis of the `PSF Translation Workgroup <translation_wg_>`_
11+
12+
Then you can bootstrap your new translation by using `cookiecutter
13+
<https://github.com/JulienPalard/python-docs-cookiecutter>`__ or
14+
`bootstrapper <https://github.com/python-docs-translations/python-docs-bootstrapper>`__.
15+
16+
The important steps look like this:
17+
18+
- Create the GitHub repo (anywhere) with the right hierarchy (using one
19+
of the bootstrappers).
20+
- Gather people to help you translate. You can't do it alone.
21+
- You can use any tool to translate, as long as you can synchronize with Git.
22+
Some use Transifex, and some use only GitHub. You can choose another
23+
way if you like; it's up to you.
24+
- Ensure we update this page to reflect your work and progress, either via a
25+
PR or by asking on the `translation mailing list <translation_ml_>`_.
26+
- When ``bugs``, ``tutorial``, and ``library/functions`` are 100%
27+
completed, ask on the `translation mailing list <translation_ml_>`_ for
28+
your language to be added in the language switcher on docs.python.org.
29+
30+
31+
PEP 545 summary
32+
===============
33+
34+
Here are the essential points of :PEP:`545`:
35+
36+
- Each translation is assigned an appropriate lowercased language tag,
37+
with an optional region subtag, and joined with a dash, like
38+
``pt-br`` or ``fr``.
39+
40+
- Each translation is under CC0 and marked as such in the README (as in
41+
the cookiecutter).
42+
43+
- Translation files are hosted on
44+
``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not
45+
mandatory to start a translation, but mandatory to land on
46+
``docs.python.org``).
47+
48+
- Translations having completed ``tutorial/``, ``library/stdtypes``
49+
and ``library/functions`` are hosted on
50+
``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``.
51+
52+
53+
Coordinating FAQ
54+
================
55+
56+
Are there tools to help in managing the repo?
57+
---------------------------------------------
58+
59+
Here's what we're using:
60+
61+
- :pypi:`pomerge` to propagate translations from one file to others.
62+
- :pypi:`pospell` to check for typos in ``.po`` files.
63+
- :pypi:`powrap` to rewrap the ``.po`` files
64+
before committing. This helps keep Git diffs short.
65+
- :pypi:`potodo` to list what needs to be translated.
66+
- :pypi:`sphinx-lint` to validate reST syntax in translation files.
67+
68+
More related tools and projects can be found in the
69+
`python-docs-translations`__ organisation on GitHub.
70+
71+
__ https://github.com/python-docs-translations
72+
73+
How is a coordinator elected?
74+
-----------------------------
75+
76+
There is no election; each translation has to sort this out. Here are some suggestions.
77+
78+
- Coordinator requests are to be public on the `translation mailing list <translation_ml_>`_.
79+
- If the given language has a native core dev, the core dev has their
80+
say on the choice.
81+
- Anyone who wants to become coordinator for their native language and shows
82+
motivation by translating and building a community will be named
83+
coordinator.
84+
- In case of concurrency between two persons, no one will sort this out
85+
for you. It is up to you two to organize a local election or whatever is
86+
needed to sort this out.
87+
- If a coordinator becomes inactive or unreachable for a long
88+
period of time, someone else can ask for a takeover on the `translation mailing list <translation_ml_>`_.
89+
90+
I have a translation, but it's not in Git. What should I do?
91+
------------------------------------------------------------
92+
93+
You can ask for help on the `translation mailing list <translation_ml_>`_, and
94+
the team will help you create an appropriate repository. You can still use tools like transifex,
95+
if you like.
96+
97+
98+
My Git hierarchy does not match yours. Can I keep it?
99+
-----------------------------------------------------
100+
101+
No, inside the ``github.com/python`` organization we’ll all have the
102+
exact same hierarchy so bots will be able to build all of our
103+
translations. So you may have to convert from one hierarchy to another.
104+
Ask for help on the `translation mailing list <translation_ml_>`_ if you’re
105+
not sure on how to do it.
106+
107+
108+
What hierarchy should I use in my GitHub repository?
109+
----------------------------------------------------
110+
111+
As for every project, we have a *branch* per version. We store ``.po``
112+
files in the root of the repository using the ``gettext_compact=0``
113+
style.
114+
115+
116+
The entry for my translation is missing/not up to date on this page
117+
-------------------------------------------------------------------
118+
119+
Ask on the `translation mailing list <translation_ml_>`_, or better, make a PR on the `devguide
120+
<https://github.com/python/devguide/>`__.

‎documentation/translations/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
============
2+
Translations
3+
============
4+
5+
.. toctree::
6+
:maxdepth: 2
7+
8+
translating
9+
coordinating

documentation/translating.rst renamed to documentation/translations/translating.rst

Lines changed: 0 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -110,53 +110,6 @@ details.
110110

111111
.. _tx: https://explore.transifex.com/python-doc/python-newest/
112112

113-
Starting a new translation
114-
==========================
115-
116-
First subscribe to the `translation mailing list <translation_ml_>`_,
117-
and introduce yourself and the translation you're starting. Translations
118-
fall under the aegis of the `PSF Translation Workgroup <translation_wg_>`_
119-
120-
Then you can bootstrap your new translation by using `cookiecutter
121-
<https://github.com/JulienPalard/python-docs-cookiecutter>`__ or
122-
`bootstrapper <https://github.com/python-docs-translations/python-docs-bootstrapper>`__.
123-
124-
The important steps look like this:
125-
126-
- Create the GitHub repo (anywhere) with the right hierarchy (using one
127-
of the bootstrappers).
128-
- Gather people to help you translate. You can't do it alone.
129-
- You can use any tool to translate, as long as you can synchronize with Git.
130-
Some use Transifex, and some use only GitHub. You can choose another
131-
way if you like; it's up to you.
132-
- Ensure we update this page to reflect your work and progress, either via a
133-
PR or by asking on the `translation mailing list <translation_ml_>`_.
134-
- When ``bugs``, ``tutorial``, and ``library/functions`` are 100%
135-
completed, ask on the `translation mailing list <translation_ml_>`_ for
136-
your language to be added in the language switcher on docs.python.org.
137-
138-
139-
PEP 545 summary
140-
===============
141-
142-
Here are the essential points of :PEP:`545`:
143-
144-
- Each translation is assigned an appropriate lowercased language tag,
145-
with an optional region subtag, and joined with a dash, like
146-
``pt-br`` or ``fr``.
147-
148-
- Each translation is under CC0 and marked as such in the README (as in
149-
the cookiecutter).
150-
151-
- Translation files are hosted on
152-
``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not
153-
mandatory to start a translation, but mandatory to land on
154-
``docs.python.org``).
155-
156-
- Translations having completed ``tutorial/``, ``library/stdtypes``
157-
and ``library/functions`` are hosted on
158-
``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``.
159-
160113

161114
How to get help
162115
===============
@@ -177,74 +130,6 @@ Consensus is to work on the current stable version. You can then propagate your
177130
translation from one branch to another using :pypi:`pomerge`.
178131

179132

180-
Are there tools to help in managing the repo?
181-
---------------------------------------------
182-
183-
Here's what we're using:
184-
185-
- :pypi:`pomerge` to propagate translations from one file to others.
186-
- :pypi:`pospell` to check for typos in ``.po`` files.
187-
- :pypi:`powrap` to rewrap the ``.po`` files
188-
before committing. This helps keep Git diffs short.
189-
- :pypi:`potodo` to list what needs to be translated.
190-
- :pypi:`sphinx-lint` to validate reST syntax in translation files.
191-
192-
More related tools and projects can be found in the
193-
`python-docs-translations`__ organisation on GitHub.
194-
195-
__ https://github.com/python-docs-translations
196-
197-
How is a coordinator elected?
198-
-----------------------------
199-
200-
There is no election; each translation has to sort this out. Here are some suggestions.
201-
202-
- Coordinator requests are to be public on the `translation mailing list <translation_ml_>`_.
203-
- If the given language has a native core dev, the core dev has their
204-
say on the choice.
205-
- Anyone who wants to become coordinator for their native language and shows
206-
motivation by translating and building a community will be named
207-
coordinator.
208-
- In case of concurrency between two persons, no one will sort this out
209-
for you. It is up to you two to organize a local election or whatever is
210-
needed to sort this out.
211-
- If a coordinator becomes inactive or unreachable for a long
212-
period of time, someone else can ask for a takeover on the `translation mailing list <translation_ml_>`_.
213-
214-
215-
The entry for my translation is missing/not up to date on this page
216-
-------------------------------------------------------------------
217-
218-
Ask on the `translation mailing list <translation_ml_>`_, or better, make a PR on the `devguide
219-
<https://github.com/python/devguide/>`__.
220-
221-
222-
I have a translation, but it's not in Git. What should I do?
223-
------------------------------------------------------------
224-
225-
You can ask for help on the `translation mailing list <translation_ml_>`_, and
226-
the team will help you create an appropriate repository. You can still use tools like transifex,
227-
if you like.
228-
229-
230-
My Git hierarchy does not match yours. Can I keep it?
231-
-----------------------------------------------------
232-
233-
No, inside the ``github.com/python`` organization we’ll all have the
234-
exact same hierarchy so bots will be able to build all of our
235-
translations. So you may have to convert from one hierarchy to another.
236-
Ask for help on the `translation mailing list <translation_ml_>`_ if you’re
237-
not sure on how to do it.
238-
239-
240-
What hierarchy should I use in my GitHub repository?
241-
----------------------------------------------------
242-
243-
As for every project, we have a *branch* per version. We store ``.po``
244-
files in the root of the repository using the ``gettext_compact=0``
245-
style.
246-
247-
248133
How should I translate code examples?
249134
-------------------------------------
250135

0 commit comments

Comments
 (0)