📙 Translate our guides in your native language! 🌍

[dukecat0]

🌐 Start translating in your language at https://hosted.weblate.org/projects/pypa/packaging-python-org/

❓ See additional information in the Contributing Guide section for Translation.

Updated: Nov. 17, 2023

---

Original post:

Hi,

I would like to ask if there is any translation plan of packaging.python.org?

[dukecat0]

@webknjaz Thanks for your reminder! I think we should add this to our translation guide as folks may make mistake like this.

[webknjaz]

Yes, that's an excellent idea. I just wanted to make sure that somebody fixes the mistakes that have been made already.

[dukecat0]

I just wanted to make sure that somebody fixes the mistakes that have been made already.

I've fixed mistakes that I have been made. I also marked some translations in pt_BR as needs editing.

@rffontenelle Please fix them.

[ewdurbin]

@rffontenelle so I looked into it and there's no per-component setting, it's project-global. And is edited at https://hosted.weblate.org/settings/pypa/ — @ewdurbin @di what can we do about this? Should we mention both projects there?

That's copy/pasted from warehouse's docs. We could probably just update it to link to https://warehouse.readthedocs.io/translations.html for warehouse and some page on packaging.python.org if you want to create it once a workflow is settled on.

[rffontenelle]

@webknjaz @meowmeowmeowcat thanks for the heads up. Fixed the ref links.

One nice syntax guide for RST docs: https://docutils.sourceforge.io/docs/user/rst/quickref.html

[dukecat0]

One nice syntax guide for RST docs: https://docutils.sourceforge.io/docs/user/rst/quickref.html

@rffontenelle Thanks for suggestion. This guide will be added to translation guideline.

[webknjaz]

@ewdurbin @di there's an alert here https://hosted.weblate.org/projects/pypa/packaging-python-org/#alerts and the :warning: symbol is displayed next to our project. It seems to imply that the PSF license is unacceptable. Could you take a look?

[rffontenelle]

@webknjaz It seems that Weblate relies on SPDX License List to tell if the license is accepted or not, which means being FSF Free/Libre and OSI Approved. This is done automagically by extracting for SPDX License List, and that list has "Python License 2.0" with Y(es) for both requirements, and "Python Software Foundation License 2.0" which does not have Y for both requirements. PyPA projects on Weblate are set with "Python Software Foundation License 2.0" as license.

If this is a incorrect result, consider filing a bug report in https://github.com/WeblateOrg/weblate/ to work this out.

[ewdurbin]

looks like @rffontenelle's analysis is correct: https://opensource.org/licenses/Python-2.0 https://www.gnu.org/licenses/license-list.en.html#Python indicate that the license is FSF and OSI approved. Might be something we need to discuss with SPDX too?

[webknjaz]

Might be something we need to discuss with SPDX too?

Yep, that's what I was thinking too.

[rffontenelle]

looks like @rffontenelle's analysis is correct: https://opensource.org/licenses/Python-2.0 https://www.gnu.org/licenses/license-list.en.html#Python indicate that the license is FSF and OSI approved. Might be something we need to discuss with SPDX too?

Let's differentiate "Python-2.0" from "Python Software Foundation License 2.0" in SPDX's point of view.

You are saying "Python-2.0", but "Python Software Foundation License 2.0" is set in Weblate, which is "PSF-2.0" according to SPDX. To SPDX, the following are two different licenses:

Full name: Python Software Foundation License 2.0 Identifier: PSF-2.0 SDPX URL: https://spdx.org/licenses/PSF-2.0.html FSF Free/Libre: (empty) OSI Approved: (empty)

Full name: Python License 2.0 Identifier: Python-2.0 SDPX URL: https://spdx.org/licenses/Python-2.0.html FSF Free/Libre: Y OSI Approved: Y

It seems you are expecting "Python-2.0" to be accepted (which is!), but the projects in Weblate were actually set with PSF-2.0's full name.

[rffontenelle]

Also, what's with CC BY-SA 3.0 license in this project's README file ?

The Python Packaging User Guide is licensed under a Creative Commons Attribution-ShareAlike license: http://creativecommons.org/licenses/by-sa/3.0.

https://packaging.python.org/ 's footnote states "This page is licensed under the Python Software Foundation License Version 2."

[webknjaz]

You are saying "Python-2.0", but "Python Software Foundation License 2.0" is set in Weblate, which is "PSF-2.0" according to SPDX.

It's interesting that both SPDX pages point at https://opensource.org/licenses/Python-2.0 in the Other web pages for this license field. And there's also this note:

This is the PSF-2.0 license, which is part of the complete Python license text, but also used independently by some projects.

So basically if Python-2.0 is libre, then its part (PSF-2.0) should also be libre...

[webknjaz]

packaging.python.org 's footnote states "This page is licensed under the Python Software Foundation License Version 2."

Looks like this is coming from the theme and is not overridden in this repo: https://github.com/python/python-docs-theme/blob/6ed468a/python_docs_theme/layout.html#L122-L125. I wonder if @pradyunsg's Furo will have the same problem — adopting it (or its derivative) will probably just drop the license mention completely).

[dukecat0]

On a side note, today I've enabled syntax highlighting in the translation fields which should make it easier to make sure that it doesn't have broken sequences.

@webknjaz Is syntax highlighting disabled?

[webknjaz]

It should be enabled.

[rffontenelle]

I see it enabled in pt_BR

[dukecat0]

It sounds very strange now. I can see that Ukrainian and pt_BR have syntax highlighting, while other languages don't have it.

[rffontenelle]

@meowmeowmeowcat Can you please provide an example and link to a string of any language which doesn't have syntax highlighting?

[dukecat0]

🤦 I know what's going on now. There is no issue with syntax highlight. Sorry for the confusion.

I forgot that the original text doesn't have syntax hightlight.

[webknjaz]

FYI @pradyunsg and I tried to come up with a workaround for auto-updating the POT file (on a social call that we have periodically) and decided that the updates should happen in the PRs with changes to the respective RST files (for many reasons, including the fact that it's seemingly impossible to make GHA / bots bypass the branch projection). To facilitate this, we'll try integrating https://pre-commit.ci so that the contributors wouldn't need to do this manually (the bot will just push the updates to their branches effectively updating the PRs).

[dukecat0]

Good idea!

To facilitate this, we'll try integrating https://pre-commit.ci so that the contributors wouldn't need to do this manually (the bot will just push the updates to their branches effectively updating the PRs).

@webknjaz Would you take care of this?

[webknjaz]

Yep, also Pradyun needs to add the integration, I don't have sufficient privileges for this.

[dukecat0]

That's great! Thank you for both of you working on this!

[webknjaz]

@meowmeowmeowcat do you know if the MO files are necessary for the localization to work? I'd prefer not to keep binaries in the repo.

[webknjaz]

Ah, there's gettext_auto_build: https://github.com/readthedocs/readthedocs.org/issues/4702#issuecomment-426556170.

[dukecat0]

Ah, there's gettext_auto_build: https://github.com/readthedocs/readthedocs.org/issues/4702#issuecomment-426556170.

Yes, and you have removed .mo files from the repo.

[webknjaz]

Ah, there's gettext_auto_build: readthedocs/readthedocs.org#4702 (comment).

Yes, and you have removed .mo files from the repo.

They are required but Sphinx generates them during the build. So it works (I've checked both locally and on RTD + added the respective setting explicitly).

[dukecat0]

They are required but Sphinx generates them during the build. So it works (I've checked both locally and on RTD + added the respective setting explicitly).

Oh, I see.

@meowmeowmeowcat do you know if the MO files are necessary for the localization to work? I'd prefer not to keep binaries in the repo.

So this is solved. :)

Now I have another question: Could you build other languages versions for the docs, for example, zh_Hans? I noticed that some language codes used by Weblate are different from Sphinx.

[webknjaz]

It looks like Sphinx doesn't validate the exact language codes. According to my tests, it accepts any string there.

[dukecat0]

Thanks for your testing. And I've also found a solution for RTD to read the language codes correctly. RTD follows the language codes given by Sphinx: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. After I checked the docs of Weblate, I think we don't have to modify our language codes now. We can add symlinks instead.

[rffontenelle]

I'm getting a check failure on a regex and I believe it shouldn't be failing. I assume the regex used is customized. Can this be verified? This is the translation string .

(Click in the images to see full size)

[dukecat0]

@rffontenelle I guess translating the string

:ref:`python_requires`

to:

:ref:`translated_text <python_requires>`

should silence this error, as Weblate assumes that it would be translated.

[rffontenelle]

@meowmeowmeowcat you guessed correctly. However :ref:`python_requires` should be considered valid too to reStructuredText, and is normally not translated AFAIK.

How about adjusting the regex to something that matches both the current state and also the original text? E.g.

:ref:`(\w+[\w\s]* <python_requires>|python_requires)`

[dukecat0]

How about adjusting the regex to something that matches both the current state and also the original text? E.g.

:ref:`(\w+[\w\s]* <python_requires>|python_requires)`

@webknjaz Could you help us on modifying this if possible? Thanks!

[webknjaz]

@rffontenelle @meowmeowmeowcat thanks for bringing this up!

Adding those checks was a lot of manual work, I haven't done this for all the strings (never got time) and I've tried to make them generic where possible. The common case is that you'd actually need a custom translation in many cases, for example, because if the linked label has a title with a different text, that title will be injected as-is. This is problematic for languages that would require that text be adapted, to be consistent with the sentence it's linked in. In the translation UI, there's no way to see what's on the "other side" of the label so I've opted for always requiring explicit text.

In your case, you're lucky that https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires got the same text as the label but have you checked this manually, or has it happened by chance? The principle that explicit is better than implicit applies here too, I think.

FWIW I've updated the check for that string.

[rffontenelle]

@webknjaz I thought it was a custom setting, but haven't thought on the work it took to set it up. Thanks for the effort, it is very appreciated.

It wasn't luck---I knew that python_requires was a term that shouldn't be translated. I normally have a tab with the translate strings in Weblate and another tab with the documentation. So I see what's the resulting the RST syntax.

But please notice that is it not mandatory to use explicit translation in reference to get translated result. When ref'ing a hyperlink target, the translated title is injected when such title was translated.

For instance, Weblated documentation has a component hyperlink target the gets replaced with "Component configuration" in original doc. However in pt_BR translation, the component target is replaced with "Configuração de componente" without expliciting such translated title. E.g. "Veja :ref:`component` para mais informações" would result in "Veja Configuração de componente para mais informações

Personally I prefer not translating the :ref: without obvious needs (e.g. plural/singular differences) to try to avoid inconsistencies (e.g. when changing the title translation).

[rffontenelle]

How can I build translated version of packaging.python.org?

While I successful build pt_BR version (confirmed due to Sphinx own translated messages), my translation in this project doesn't land in the HTML pages. I'm using the following command:

sphinx-build -b html -d build/doctrees --keep-going -jauto -D locale_dirs=locales -D language=pt_BR source build/html

[webknjaz]

@webknjaz I thought it was a custom setting, but haven't thought on the work it took to set it up. Thanks for the effort, it is very appreciated.

Well, it is sorta custom depending on the PoV. It's implemented via "flags" that are documented here: https://docs.weblate.org/en/latest/admin/checks.html#custom-checks. I've set some flags globally for the project, like the list of common terms/abbreviations. It gets inherited by all the strings but can be overridden for each string separately. I've gone through a bunch of those that have RST and added this regex that you saw. Usually, you should see the flags in the sidebar. Here's an example: And editing that looks like this:

I'm trying to add these checks so that they are useful across languages and help many people.

It wasn't luck---I knew that python_requires was a term that shouldn't be translated. I normally have a tab with the translate strings in Weblate and another tab with the documentation. So I see what's the resulting the RST syntax.

But please notice that is it not mandatory to use explicit translation in reference to get translated result. When ref'ing a hyperlink target, the translated title is injected when such title was translated.

This is exactly the problem. You don't see what's on the other side. Moreover, if the title under that ref changes in the future, this will happen separately from updating the references in many cases.

Currently, it's

.. _python_requires:

``python_requires``
~~~~~~~~~~~~~~~~~~~

meaning that it'll be python_requires in the rendered text:

use the :ref:`python_requires` argument

will become

use the <a href=...>python_requires</a> argument

when rendered. But imagine it changes like this:

 .. _python_requires:

-``python_requires``
+``python_requires`` explanation
 ~~~~~~~~~~~~~~~~~~~

then the render will silently become

use the <a href=...>python_requires explanation</a> argument

breaking the sentence structure/grammar/etc.

The translators will not get notified until somebody sees this on the published site which is what I'm trying to avoid by making sure that the sentences with the references are always consistent.

For instance, Weblated documentation has a component hyperlink target the gets replaced with "Component configuration" in original doc. However in pt_BR translation, the component target is replaced with "Configuração de componente" without expliciting such translated title. E.g. "Veja :ref:component para mais informações" would result in "Veja Configuração de componente para mais informações

Personally I prefer not translating the :ref: without obvious needs (e.g. plural/singular differences) to try to avoid inconsistencies (e.g. when changing the title translation).

I know what you're talking about but many people would not notice the lack or the presence of this "obvious" need when going through the list of the strings during the translation and this burden then becomes translation editor's.

With automatic validation, the chance of getting into this sort of trouble is lower which is why I've gone for it in the first place.

[webknjaz]

How can I build translated version of packaging.python.org?

I think I've added a nox target for this earlier. For Ukrainian, I used to run python -m nox -s build -- -D language=uk (just found it in my terminal history). Also, I've set up a separate RTD site with manual builds and a different language selected: https://packagingpythonorg-uk-ua.rtfd.io — it took a few tries to figure out the proper locale name matching what RTD has in their selector. Could do the same for pt-BR.

[webknjaz]

@rffontenelle I've created an RTD site for pt-BR here https://packagingpythonorg-pt-br.rtfd.io. The build seems to complete successfully: https://readthedocs.org/projects/packagingpythonorg-pt-br/builds/15270285/. If you log in to RTD and give me your username there, I'll add you to the project so you could experiment with rebuilding the site occasionally. This is only for testing, of course. When at least one of the languages gets 90-95% of the content translated, we'll think about how to best deploy this for wider consumption.

[rffontenelle]

@webknjaz

Regarding our ref talk above, you understood my idea. And I understand that if the target string changes ("python_requires explanation" in your example), will changes how it is rendered. My thinking on this is: I translate making sure it renders properly in the documentation, also with proper grammar. If the "python_requires" title changes, I'll translate it as well. It might require some change around the documentation if any. On the other side, imagine having to change all occurrences of "python_requires" in translation due to title change -- IMHO, it would require more work and very prone to inconsistency.

Let me promise this, now and then I will build the documentation with the up-to-date PO file (or using RTD) to make sure it doesn't have Sphinx WARNINGS -- I do this for pt_BR translation of Python Docs.

---

Regarding flags in Weblate UI, no, can't see the regex on my side. It is probably visible only to the project's admins.

---

My RTD account is rafaelff

Thanks for setting up a testing website. It will be very useful.

[rffontenelle]

For the record, that's how I locally built pt_BR version of packaging.python.org:

pip install nox    # if not installed already
nox -s translation
wget https://hosted.weblate.org/download/pypa/packaging-python-org/pt_BR/ -O locales/pt_BR/LC_MESSAGES/messages.po
msgmerge --update --previous locales/pt_BR/LC_MESSAGES/messages.po locales/messages.pot
nox -s build -- -D language=pt_BR

It should work for any other language, replacing pt_BR with the proper language code.

[webknjaz]

Regarding our ref talk above, you understood my idea. And I understand that if the target string changes ("python_requires explanation" in your example), will changes how it is rendered. My thinking on this is: I translate making sure it renders properly in the documentation, also with proper grammar. If the "python_requires" title changes, I'll translate it as well. It might require some change around the documentation if any. On the other side, imagine having to change all occurrences of "python_requires" in translation due to title change -- IMHO, it would require more work and very prone to inconsistency.

Let me promise this, now and then I will build the documentation with the up-to-date PO file (or using RTD) to make sure it doesn't have Sphinx WARNINGS -- I do this for pt_BR translation of Python Docs.

I see. Well, my thinking was that this approach would let people not care about the title updates since the context of where the references are used probably wouldn't change and wouldn't require changed wording. I'd argue that unanchored refs shouldn't be used in the source either because of the untraceable implications of the side effects caused by this.

Regarding flags in Weblate UI, no, can't see the regex on my side. It is probably visible only to the project's admins.

Ah, I wasn't sure about that, this is why I've added those screenshots. But if you see something that may benefit from extra validation, let me know.

My RTD account is rafaelff

Thanks for setting up a testing website. It will be very useful.

Invited.

[webknjaz]

For the record, that's how I locally built pt_BR version of packaging.python.org:

pip install nox    # if not installed already
nox -s translation
wget https://hosted.weblate.org/download/pypa/packaging-python-org/pt_BR/ -O locales/pt_BR/LC_MESSAGES/messages.po
msgmerge --update --previous locales/pt_BR/LC_MESSAGES/messages.po locales/messages.pot
nox -s build -- -D language=pt_BR

It should work for any other language, replacing pt_BR with the proper language code.

Maybe you could add a new target for this to the noxfile? I guess some of the other translators could benefit from this.

[rffontenelle]

Strings containing hyperlinks without a target cannot be translated without Sphinx bringing up warning, which will always popup as error when sphinx-build has -W flag enabled (recommended when in CI).

e.g.: translating `API token`_ from guides/distributing-packages-using-setuptools.rst to `token de API`_ or `token de API <token de API>`_ will result in:

... /guides/distributing-packages-using-setuptools.rst:904: WARNING: inconsistent references in translated message. original: ['`API token`_'], translated: []

EDIT: Note, hyperlinks with a target would be `text <link>`_

I'm thinking about translating all the guide in order to map all problematic cases for translation, opening a tracker issue and presenting PR with changes to work around them.

Any thoughts on the change?

[rffontenelle]

FWIW "Translations" GitHub Actions is failing to update POT with msg "protected branch hook declined", requiring an approval.

[di]

Here's a link to a failed run: https://github.com/pypa/packaging.python.org/runs/4290954151

[webknjaz]

Strings containing hyperlinks without a target cannot be translated without Sphinx bringing up warning, which will always popup as error when sphinx-build has -W flag enabled (recommended when in CI).

e.g.: translating `API token`_ from guides/distributing-packages-using-setuptools.rst to `token de API`_ or `token de API <token de API>`_ will result in:

... /guides/distributing-packages-using-setuptools.rst:904: WARNING: inconsistent references in translated message. original: ['`API token`_'], translated: []

EDIT: Note, hyperlinks with a target would be `text ` ``_

I'm thinking about translating all the guide in order to map all problematic cases for translation, opening a tracker issue and presenting PR with changes to work around them.

Any thoughts on the change?

Have you tried keeping the original reference between angled brackets? As in:

`token de API <API token>`_

Tell me if it works and maybe I'd add more of those regex rules.

---

FWIW "Translations" GitHub Actions is failing to update POT with msg "protected branch hook declined", requiring an approval.

Yeah, I know, thanks. Pradyun and I have been brainstorming possible solutions on a few of our calls. GHA (and GH Apps) cannot skip branch protection (for various reasons). I wanted to apply a workaround but Pradyun didn't like the idea and suggested integrating pre-commit.ci so that it'd be autogenerated on each PR. But on our last meeting we realized that this may cause more problems. Pradyun suggested another solution — remove the POT file from the main branch and have an automation generating and committing it into a separate "translation" branch which would avoid conflicts. Apparently, Weblate is able to source the POT file from a different branch than it pushes the MO files back to. We want to try it out but I haven't had time to actually experiment with this.

[webknjaz]

@meowmeowmeowcat FYI I've pinned this issue and turned it into a call to action.