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 @@ + + pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy