You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide is intended for language teams working on the Python documentation within the python-doc_ organization on Transifex_. Yes: not all teams translate on Transifex, so using Transifex is optional.
5
+
This guide is intended for language teams working on the Python documentation
6
+
within the python-doc_ organization on Transifex_. Yes: not all teams translate
If you are new to the translation of Python documentation, we recommend that you start by reading the Translating_ on `Python Developer's Guide`_ (a.k.a. devguide), joining the relevant contact channels, and familiarizing yourself with `PEP 545`_.
16
+
To ensure that translations are of a good standard, it is essential that you are
17
+
confident in both English and the translation language.
15
18
16
-
If there is already a repository for your language team, please join and introduce yourself to the team.
19
+
If you are new to the translation of Python documentation, we recommend that
20
+
you start by reading the Translating_ on `Python Developer's Guide`_
21
+
(a.k.a. devguide), joining the relevant contact channels, and familiarizing
22
+
yourself with `PEP 545`_.
17
23
18
-
**If there is no existing repository or language team, you will need to create one.** Simply translating on Transifex is not enough to have your language published in the Python documentation. Please follow the instructions on starting a new translation.
24
+
If there is already a repository for your language team, please join and
25
+
introduce yourself to the team.
26
+
27
+
**If there is no existing repository or language team, you will need to create
28
+
one.** Simply translating on Transifex is not enough to have your language
29
+
published in the Python documentation. Please follow the instructions on starting
@@ -25,7 +37,8 @@ If there is already a repository for your language team, please join and introdu
25
37
Geting to Know Transifex
26
38
~~~~~~~~~~~~~~~~~~~~~~~~
27
39
28
-
If you are new to Transifex, it is recommended that you take the time to read through the following resources from the Transifex documentation:
40
+
If you are new to Transifex, it is recommended that you take the time to read
41
+
through the following resources from the Transifex documentation:
29
42
30
43
- `Getting started as a translator <https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator>`_: This covers signing up for an account and joining translation team.
31
44
- `Translating with the Web Editor <https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor>`_: This covers getting to the editor, searching and filtering strings, and translating strings.
@@ -36,41 +49,70 @@ If you are new to Transifex, it is recommended that you take the time to read th
36
49
Transifex Does Not Update docs.python.org
37
50
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
51
39
-
Language teams must download and store the translation files in their VCS repository, as per instructions from Translating_ on `Python Developer's Guide`_, as it is from this repository that the python-docs infrastructure will fetch translations, build the translated docs, and publish them on docs.python.org.
52
+
Language teams must download and store the translation files in their VCS
53
+
repository, as per instructions from Translating_ on `Python Developer's Guide`_,
54
+
as it is from this repository that the python-docs infrastructure will fetch
55
+
translations, build the translated docs, and publish them on docs.python.org.
40
56
41
57
Projects within python-doc
42
58
~~~~~~~~~~~~~~~~~~~~~~~~~~
43
59
44
-
The python-doc_ organization contains several projects, each representing the documentation for a specific version of Python (e.g. 3.11). The "Python" project (slug "python-newest") is the latest version available for translation. All other projects are named "Python <version>".
60
+
The python-doc_ organization contains several projects, each representing the
61
+
documentation for a specific version of Python (e.g. 3.11). The "Python" project
62
+
(slug "python-newest") is the latest version available for translation. All other
63
+
projects are named "Python <version>".
45
64
46
65
47
66
The Latest Version for Translation
48
67
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
49
68
50
-
The "Python" project in Transifex always contains the latest stable release of Python or its latest beta/RC release, but not alpha releases. For example, if the latest version is 3.12, the "Python" project will only be updated with strings from the 3.13 branch when a beta is released.
69
+
The "Python" project in Transifex always contains the latest stable release of
70
+
Python or its latest beta/RC release, but not alpha releases. For example, if
71
+
the latest version is 3.12, the "Python" project will only be updated with
72
+
strings from the 3.13 branch when a beta is released.
51
73
52
74
53
75
Translate the Latest Version
54
76
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55
77
56
-
Translations are propagated across projects for the same string, meaning that you only need to translate once and all versions of the Python documentation will receive the contribution *if the string remains unchanged*. If a string has changed between versions, the contribution will not be applied to the new version.
78
+
Translations are propagated across projects for the same string, meaning that
79
+
you only need to translate once and all versions of the Python documentation
80
+
will receive the contribution *if the string remains unchanged*. If a string has
81
+
changed between versions, the contribution will not be applied to the new version.
57
82
58
-
It is recommended to focus your translation efforts on the "Python" project, which represents the newest version. Keep in mind that the Python documentation contains a large number of strings and that translations will be propagated, so older versions will receive most contributions. Additionally, translating the newest version is more important as it will have fewer differences from the source string and receive more contributions.
83
+
It is recommended to focus your translation efforts on the "Python" project,
84
+
which represents the newest version. Keep in mind that the Python documentation
85
+
contains a large number of strings and that translations will be propagated, so
86
+
older versions will receive most contributions. Additionally, translating the
87
+
newest version is more important as it will have fewer differences from the source
88
+
string and receive more contributions.
59
89
60
90
61
91
Placeholders
62
92
~~~~~~~~~~~~
63
93
64
-
When translating in Transifex, you will encounter strings with `custom placeholders <placeholders.rst>`_ in the form of Sphinx roles (e.g. \:class:\`turtle`). These placeholders help highlight the role of specific elements, making it easier to translate them correctly and avoid warnings from Transifex if they are translated incorrectly.
94
+
When translating in Transifex, you will encounter strings with `custom
95
+
placeholders <placeholders.rst>`_ in the form of Sphinx roles (e.g. \:class:\`turtle`).
96
+
These placeholders help highlight the role of specific elements, making it easier to
97
+
translate them correctly and avoid warnings from Transifex if they are translated incorrectly.
65
98
66
-
For instance, if the source string contains ``:class:`turtle```, the translation string should also include the same placeholder. If it's missing, Transifex will display a warning message.
99
+
For instance, if the source string contains ``:class:`turtle```, the translation
100
+
string should also include the same placeholder. If it's missing, Transifex will
101
+
display a warning message.
67
102
68
-
Occasionally, you may encounter false-positives in the warnings. It is important to check these warnings before ignoring them to ensure accuracy.
103
+
Occasionally, you may encounter false-positives in the warnings. It is important
104
+
to check these warnings before ignoring them to ensure accuracy.
69
105
70
106
Final words
71
107
~~~~~~~~~~~
72
108
73
-
It is recommended that you also follow the style guide for your language and review any existing translations to understand the tone and style of the language team. Translating the Python documentation can be a large project, and contributions from many members of the community are appreciated. If you need help or have questions, please reach out to the language team or any other contact channel provided in Translating_ on `Python Developer's Guide`_, or contact the python-doc project coordinators on Transifex.
109
+
It is recommended that you also follow the style guide for your language and
110
+
review any existing translations to understand the tone and style of the language
111
+
team. Translating the Python documentation can be a large project, and contributions
112
+
from many members of the community are appreciated. If you need help or have
113
+
questions, please reach out to the language team or any other contact channel
114
+
provided in Translating_ on `Python Developer's Guide`_, or contact the
0 commit comments