diff --git a/contrib/index.rst b/contrib/index.rst index b93d36504..f9b54bc56 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -75,7 +75,7 @@ major section at the top of each column.]* * :ref:`documenting` * :ref:`style-guide` * :ref:`rst-primer` - * :doc:`documentation/translations` + * :ref:`translating` * :ref:`devguide` - * :ref:`setup` diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 4e78b9247..9cb5e9828 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -3,47 +3,152 @@ Coordinating ============ Information about the Python documentation translation processes is -found in this devguide and :PEP:`545`. -Translations are built by `docsbuild-scripts -`__ and hosted on -docs.python.org. Translations -are overseen by the `Editorial Board `_ +found on this page and in :PEP:`545`. Translations are overseen by the +`Editorial Board `_. + +.. _translation-help: + +Communication/help channels +=========================== + +Discussions about translations occur on the Python Docs Discord +`#translations channel `_, `translation +mailing list `_, and the +`translations category `_ of the Python Discourse. + +For administrative issues, ping ``@python/editorial-board``. + Starting a new translation ========================== -First subscribe to the `translation mailing list `_, -and introduce yourself and the translation you're starting. +Coordination is not a one-off task, it is a long-term commitment. Before +you start your translation, carefully consider if you will be able to commit +to this. +Every coordinator should be familiar with translating: see :ref:`translating`. + +The following sections will guide you through setting up your translation. +If you have any questions or need help, ask in one of the +:ref:`help channels `. + + +Announcement +------------ + +Post an announcement introducing yourself and the translation you're +starting on `Discourse `_. Also join the other communication +channels, if possible. + + +Coordination team +----------------- + +Each translation team will decide on the number of coordinators. +While initially one person is fine, we recommend expanding to having two or +three coordinators. You can find more on choosing coordinators in the FAQ +section on this page. + + +Translation team +---------------- + +.. figure:: translator-workload.svg + :class: invert-in-dark-mode + :align: center + :alt: An exaggerated chart showing that individual translator workload + decreases with the amount of translators. + + +Gather people to translate with you. You can't do it alone. +Update :ref:`this table ` via a PR on the devguide +to make your translation easier to find. In the entry you can also include links +to guides or other resources for translators. + + +Repository +---------- + +To start your translation create a GitHub repository, under any +account, with the correct Git hierarchy and folder structure. This can be done +in several ways, and depends on what translation process you plan to use. + +Each translation is assigned an appropriate lowercase +`IETF language tag `_. +The tag may have an optional subtag, joined with a dash. +For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). +The repository name is then: ``python-docs-TAG`` + +The name of each branch should be the Python version it holds translations +for, for example, ``3.14``. The files should be structured like the source files +in `CPython/Doc `_. +A correctly set up repository looks like this: +`python-docs-pl `_ + +Below, the recommended ways for starting your repository are described. You can +choose another way if you like; it’s up to you. + + +Cookiecutter/bootstrapper +~~~~~~~~~~~~~~~~~~~~~~~~~ -Then you can bootstrap your new translation by using the `cookiecutter +You can bootstrap your new translation by using the `cookiecutter `__ or `bootstrapper `__. -You can also start your translation using `Transifex `_ -following this `guide `_. +The repository can then be used with a pull-request based translation process. -The important steps look like this: -- Create the GitHub repo (any account) with the correct hierarchy by using one - of the bootstrappers or Transifex. -- Gather people to help you translate. You can't do it alone. -- You can use any tool to translate, as long as you can synchronize with Git. - Some use Transifex, and some use only GitHub. You can choose another - way if you like; it's up to you. -- Update :doc:`this page ` to reflect your work and progress, either via a - PR or by asking on the `translation mailing list `_. -- When ``bugs``, ``tutorial``, and ``library/functions`` are 100% - completed, ask on the `translation mailing list `_ for - your language to be added in the language switcher on docs.python.org. +Translation platform +~~~~~~~~~~~~~~~~~~~~ +You can also start your translation using +`Transifex `_. +This will allow you to translate via the web interface, and to use shared +automatically updated source files. -How to get help -=============== +This is best done with a workflow that periodically checks for translations, +a sample one with instructions can be found in the +`python-docs-tx-automations documentation `__. +An in depth guide for manually doing this can also be found +in the same documentation's +`commands page `__. -Discussions about translations occur on the Python Docs Discord -`#translations channel `_, `translation -mailing list `_, and the -`translations category `_ -of the Python Discourse. +To be added as the coordinator(s) on Transifex for your language, open an issue +in the `tracker `__. + + +Glossary +-------- + +Each translation team should have a way to store translations of terms to ensure +consistency. This is often done with a glossary. More information about the use +of glossaries can be found in the :ref:`translation-style-guide`. + + +Moving the repo to the ``python`` org +------------------------------------- + +This will allow you to plug your translation into docsbuild-scripts_, and it +will be found at ``docs.python.org/LANG/``, but not in the switcher. + +.. XXX When ...? Discussion needed... +.. My idea: Time based, e.g. 2 months of activity, showing that they aren't going anywhere + +Adding to the language switcher +------------------------------- + +.. XXX Specify branch: https://github.com/python/devguide/issues/1586 + +Once the following resources have been fully translated: + +- ``bugs.po``, with proper links to the language repository issue tracker +- all files in the ``tutorial/`` folder +- ``library/functions.po``, the page documenting builtins + +The translation can be added to the language switcher. This can be done with a +pull request to docsbuild-scripts_, like `this commit `__ +if your translation was previously built but not in the switcher, or like +`this commit `__ +if this is it's initial addition. PEP 545 summary @@ -51,31 +156,34 @@ PEP 545 summary Here are the essential points of :PEP:`545`: -- Each translation is assigned an appropriate lowercased language tag, - with an optional region subtag, and joined with a dash, like - ``pt-br`` or ``fr``. +- Each translation is assigned an appropriate lowercase + `IETF language tag `_. + The tag may have an optional region subtag, joined with a dash. + For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). -- Each translation is under CC0 and marked as such in the README (as in - the cookiecutter). +- Each translation is under CC0 and is marked as such in the README. -- Translation files are hosted on - ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not - mandatory to start a translation, but mandatory to land on - ``docs.python.org``). +- Translation files are hosted in repositories under the Python org: + ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` -- Translations having completed ``tutorial/``, ``library/stdtypes`` - and ``library/functions`` are hosted on - ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. +- Translations having completed ``bugs``, ``tutorial/`` + and ``library/functions`` are added to the language switcher. -Transifex -========= +Translating Sphinx +================== -If you need help from a Transifex administrator, open an issue on the -`tracker `_. +Some messages that appear in the docs must be translated in the +`Sphinx project `__ +(`sphinx-doc on Transifex `__) or in +the `python-docs-theme `_ +(currently this is not possible; see this +`issue `__). +Coordinators should direct some translators there, so that the documentation +is fully translated. -Coordinating FAQ +Coordination FAQ ================ Are there tools to help in managing the repo? @@ -96,12 +204,26 @@ More related tools and projects can be found in the __ https://github.com/python-docs-translations -How is a coordinator elected? ------------------------------ + +How should I test my translation? +--------------------------------- + +Testing should ideally be set up in your repository, and will help catch errors +early and ensure translation quality. Testing generally consists of building, and +linting with :pypi:`sphinx-lint`. + +See `this documentation `_ +for sample workflows with usage guides. + +The `dashboard `_ +also tests translations and uploads error logs. + + +How is a coordination team chosen? +---------------------------------- Each translation team will decide on the number of coordinators. We recommend two or three coordinators, though you may begin with one. -Here are some general suggestions. - Coordinator requests are to be public on the `translation mailing list `_. - If the given language has a native core dev, the core dev has input @@ -112,25 +234,28 @@ Here are some general suggestions. - We expect the local community to self-organize coordinators and contributors. If you have questions, please ask on the mailing list or Discourse. - If a coordinator becomes inactive or unreachable for a long - period of time, someone else can ask to be added as a primary coordinator on the `translation mailing list `_. - As a community resource, we aim to keep translations up to date with active contributors, including coordinators. + period of time, someone else can ask to be added as a primary coordinator on + the `translation mailing list `_. + As a community resource, we aim to keep translations up to date with active + contributors, including coordinators. + I have a translation, but it's not in Git. What should I do? ------------------------------------------------------------ -You can ask for help on the `translation mailing list `_, and -the team will help you create an appropriate repository. You can still use tools like transifex, -if you like. +You can ask for help in one of the :ref:`translation-help`, and +the team will help you create an appropriate repository. You can still use tools +like Transifex, if you like. My Git hierarchy does not match yours. Can I keep it? ----------------------------------------------------- -No, inside the ``github.com/python`` organization we’ll all have the +No, inside the ``github.com/python`` organization all repositories must 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 `translation mailing list `_ if you’re -not sure on how to do it. +translations. So, you may have to convert from one hierarchy to another. +Ask for help in one of the :ref:`translation-help` if you’re not sure on how to +do it. What hierarchy should I use in my GitHub repository? @@ -141,9 +266,6 @@ files in the root of the repository using the ``gettext_compact=0`` style. -.. XXX Explain necessary folder structure - - Which version of the Python documentation should be translated? --------------------------------------------------------------- @@ -154,8 +276,14 @@ propagate your translation from one branch to another using :pypi:`pomerge`. The entry for my translation is missing or not up to date --------------------------------------------------------- -Ask on the `translation mailing list `_, or better, make a PR -on the `devguide `__. +Make a PR on the `devguide `__ to update it. + + +How are translations built? +--------------------------- + +Translations are built by `docsbuild-scripts `__ +and hosted on docs.python.org. Is there a Weblate instance we can translate on? @@ -168,3 +296,5 @@ for updates. .. _EB: https://python.github.io/editorial-board/ .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ +.. _trans_disc: https://discuss.python.org/c/documentation/translations/ +.. _docsbuild-scripts: https://github.com/python/docsbuild-scripts diff --git a/documentation/translations/index.rst b/documentation/translations/index.rst index 2f5cfe0f4..a6d4dc4e7 100644 --- a/documentation/translations/index.rst +++ b/documentation/translations/index.rst @@ -3,7 +3,7 @@ Translations ============ .. toctree:: - :maxdepth: 3 + :maxdepth: 4 translating coordinating diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 7d1e2f251..dce6becfc 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -1,3 +1,5 @@ +.. _translating: + =========== Translating =========== @@ -9,7 +11,7 @@ in production and can be found in the language switcher; others are works in progress. To get started read your repository's contributing guide, which is generally the ``README`` file, and this page. If your language isn’t listed below, feel free to start the translation! -See :doc:`coordinating` guide to get started. +See :doc:`coordination ` to get started. For more details about translations and their progress, see `the dashboard `__. @@ -124,12 +126,13 @@ General discussions about translations occur on the Python Docs Discord mailing list `_, and the `translations category <_discourse>`_ of the Python Discourse. +.. _translation-style-guide: Style guide =========== Before translating, you should familiarize yourself with the general -documentation :doc:`style guide<../style-guide>`. Some translation-specific +documentation :doc:`style guide <../style-guide>`. Some translation-specific guidelines are explained below. @@ -155,7 +158,7 @@ The Python docs contain many roles (``:role:`target```) that link to other parts of the documentation. Do not translate reStructuredText roles targets, such as ``:func:`print``` or ``:ref:`some-section``` because it will break the link. -If alternate text (``:role:`text ``` is provided, it generally +If alternate text (``:role:`text ```) is provided, it generally should be translated. You can also introduce alternate text for translation if the target is not a name or term. @@ -277,8 +280,8 @@ The coordination team for my language is inactive, what do I do? ---------------------------------------------------------------- If you would like to coordinate, open a pull request in the -`devguide `_ adding yourself, and ping -``@python/editorial-board``. +`devguide `_ adding yourself to the table +at the top of this page, and ping ``@python/editorial-board``. .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ diff --git a/documentation/translations/translator-workload.svg b/documentation/translations/translator-workload.svg new file mode 100644 index 000000000..e3e131861 --- /dev/null +++ b/documentation/translations/translator-workload.svg @@ -0,0 +1,191 @@ + + + + + + + + 2025-06-29T10:46:39.952440 + image/svg+xml + + + Matplotlib v3.10.3, https://matplotlib.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +