diff --git a/conf.py b/conf.py index ba7ee6040..bedd99c42 100644 --- a/conf.py +++ b/conf.py @@ -127,6 +127,10 @@ # Documentation "docquality.rst": "documentation/help-documenting.rst", "documenting.rst": "documentation/start-documenting.rst", + # Translating + "documentation/translating.rst": "documentation/translations/translating.rst", + "translating.rst": "documentation/translations/translating.rst", + "coordinating.rst": "documentation/translations/coordinating.rst", # Getting Started "fixingissues.rst": "getting-started/fixing-issues.rst", "help.rst": "getting-started/getting-help.rst", diff --git a/documentation/index.rst b/documentation/index.rst index 3f2512bcf..eaa9e1a96 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -9,5 +9,5 @@ Documentation help-documenting style-guide markup - translating + translations/index devguide diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst new file mode 100644 index 000000000..3d64858ad --- /dev/null +++ b/documentation/translations/coordinating.rst @@ -0,0 +1,123 @@ +============ +Coordinating +============ + +Starting a new translation +========================== + +First subscribe to the `translation mailing list `_, +and introduce yourself and the translation you're starting. Translations +fall under the aegis of the `PSF Translation Workgroup `_ + +Then you can bootstrap your new translation by using `cookiecutter +`__ or +`bootstrapper `__. + +The important steps look like this: + +- Create the GitHub repo (any account) with the correct hierarchy by using one + of the bootstrappers. +- 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. + + +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 under CC0 and marked as such in the README (as in + the cookiecutter). + +- 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``). + +- Translations having completed ``tutorial/``, ``library/stdtypes`` + and ``library/functions`` are hosted on + ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. + + +Coordinating FAQ +================ + +Are there tools to help in managing the repo? +--------------------------------------------- + +Here's what we're using: + +- :pypi:`pomerge` to propagate translations from one file to others. +- :pypi:`pospell` to check for typos in ``.po`` files. +- :pypi:`powrap` to rewrap the ``.po`` files + before committing. This helps keep Git diffs short. +- :pypi:`potodo` to list what needs to be translated. +- :pypi:`sphinx-lint` to validate reST syntax in translation files. + +More related tools and projects can be found in the +`python-docs-translations`__ organisation on GitHub. + +__ https://github.com/python-docs-translations + +How is a coordinator elected? +----------------------------- + +There is no election. Each translation will sort out the number of coordinators. We recommend 2 or 3 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 + on the coordinator request. +- Anyone who wants to become coordinator for their native language and shows + motivation by translating and building a community will be named + coordinator. +- 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. + +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. + + +My Git hierarchy does not match yours. Can I keep it? +----------------------------------------------------- + +No, inside the ``github.com/python`` organization we’ll all 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. + + +What hierarchy should I use in my GitHub repository? +---------------------------------------------------- + +As for every project, we have a *branch* per version. We store ``.po`` +files in the root of the repository using the ``gettext_compact=0`` +style. + + +The entry for my translation is missing/not up to date on this page +------------------------------------------------------------------- + +Ask on the `translation mailing list `_, or better, make a PR on the `devguide +`__. + +.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter +.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ diff --git a/documentation/translations/index.rst b/documentation/translations/index.rst new file mode 100644 index 000000000..67ab049f9 --- /dev/null +++ b/documentation/translations/index.rst @@ -0,0 +1,9 @@ +============ +Translations +============ + +.. toctree:: + :maxdepth: 2 + + translating + coordinating diff --git a/documentation/translating.rst b/documentation/translations/translating.rst similarity index 55% rename from documentation/translating.rst rename to documentation/translations/translating.rst index abbd2c74f..47f04cef8 100644 --- a/documentation/translating.rst +++ b/documentation/translations/translating.rst @@ -110,53 +110,6 @@ details. .. _tx: https://explore.transifex.com/python-doc/python-newest/ -Starting a new translation -========================== - -First subscribe to the `translation mailing list `_, -and introduce yourself and the translation you're starting. Translations -fall under the aegis of the `PSF Translation Workgroup `_ - -Then you can bootstrap your new translation by using `cookiecutter -`__ or -`bootstrapper `__. - -The important steps look like this: - -- Create the GitHub repo (anywhere) with the right hierarchy (using one - of the bootstrappers). -- 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. -- Ensure we update 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. - - -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 under CC0 and marked as such in the README (as in - the cookiecutter). - -- 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``). - -- Translations having completed ``tutorial/``, ``library/stdtypes`` - and ``library/functions`` are hosted on - ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. - How to get help =============== @@ -177,74 +130,6 @@ Consensus is to work on the current stable version. You can then propagate your translation from one branch to another using :pypi:`pomerge`. -Are there tools to help in managing the repo? ---------------------------------------------- - -Here's what we're using: - -- :pypi:`pomerge` to propagate translations from one file to others. -- :pypi:`pospell` to check for typos in ``.po`` files. -- :pypi:`powrap` to rewrap the ``.po`` files - before committing. This helps keep Git diffs short. -- :pypi:`potodo` to list what needs to be translated. -- :pypi:`sphinx-lint` to validate reST syntax in translation files. - -More related tools and projects can be found in the -`python-docs-translations`__ organisation on GitHub. - -__ https://github.com/python-docs-translations - -How is a coordinator elected? ------------------------------ - -There is no election; each translation has to sort this out. Here are some 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 their - say on the choice. -- Anyone who wants to become coordinator for their native language and shows - motivation by translating and building a community will be named - coordinator. -- In case of concurrency between two persons, no one will sort this out - for you. It is up to you two to organize a local election or whatever is - needed to sort this out. -- If a coordinator becomes inactive or unreachable for a long - period of time, someone else can ask for a takeover on the `translation mailing list `_. - - -The entry for my translation is missing/not up to date on this page -------------------------------------------------------------------- - -Ask on the `translation mailing list `_, or better, make a PR on the `devguide -`__. - - -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. - - -My Git hierarchy does not match yours. Can I keep it? ------------------------------------------------------ - -No, inside the ``github.com/python`` organization we’ll all 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. - - -What hierarchy should I use in my GitHub repository? ----------------------------------------------------- - -As for every project, we have a *branch* per version. We store ``.po`` -files in the root of the repository using the ``gettext_compact=0`` -style. - - How should I translate code examples? ------------------------------------- @@ -252,5 +137,4 @@ Translate values in code examples (i.e. string literals) and comments. Don't translate keywords or names, including variable, function, class, argument, and attribute names. -.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/