📙 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?

[webknjaz]

Hi @meowmeowmeowcat, no. At the moment nobody raised this question AFAIK. But I like the idea and I think it would be great to set up a translation process. This may require a discussion with other maintainers first, but I'd definitely support such an effort.

[webknjaz]

@pypa/packaging-user-guide-editors @ewdurbin @di @pradyunsg do you think it'd be possible to use Warehouse's Weblate for this? I think the configuration pointers are present here https://docs.weblate.org/en/latest/devel/sphinx.html.

[webknjaz]

@meowmeowmeowcat as a side note, the translation would require a dedicated person per language to continuously update the articles as the canonical English versions change and new articles appear. Would you commit to something like this? You'd need to take ownership over curating your language.

[pradyunsg]

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

None at this time, no.

Sphinx and ReadTheDocs have fairly strong internationalization support -- so if someone is interested in translating and maintaining that translated guide, I'm pretty sure we can make that happen. Personally, I wouldn't be pushing for setting up that infrastructure and figuring those details out, unless someone is actually interested in doing the translation.

[anxolerd]

It would be nice to have packaging.python.org in different languages. I would even contribute to Ukrainian translation time to time, but, unfortunately i cannot constantly look at the original English articles and update translation on daily or weekly basis

[dukecat0]

@meowmeowmeowcat as a side note, the translation would require a dedicated person per language to continuously update the articles as the canonical English versions change and new articles appear. Would you commit to something like this? You'd need to take ownership over curating your language.

Sure.

[dukecat0]

None at this time, no.

Sphinx and ReadTheDocs have fairly strong internationalization support -- so if someone is interested in translating and maintaining that translated guide, I'm pretty sure we can make that happen. Personally, I wouldn't be pushing for setting up that infrastructure and figuring those details out, unless someone is actually interested in doing the translation.

Actually I am interested in doing the translation and that's why I opened this issue. 🤣

[webknjaz]

@meowmeowmeowcat it would be useful if somebody checked what we need to start doing this and maybe outlined the mechanics of the whole process. PRs adding the necessary configuration (including CI checks and a guide for translators into existing and new languages) are welcome too.

[dukecat0]

@webknjaz Is it possible to create a new translation project under pypa on weblate?

[dukecat0]

I have already made an example on Weblate.

[dukecat0]

So I think here are the few steps we have to do for starting the translation:

• We should generate .po of the docs for translation (which is done)
• Put .po files on the Weblate
• Add Translation CI check
• Writing a guide for Translators

[webknjaz]

@webknjaz Is it possible to create a new translation project under pypa on weblate?

Probably yes. But I don't have such access. That's why I've tagged @di and @ewdurbin earlier — they should have a better answer to how this could be implemented.

[webknjaz]

• We should generate .po of the docs for translation (which is done)
• Put .po files on the Weblate

I think the Weblate bot (integration?) is able to generate those files if set up properly. My understanding is that we'll need to generate them often or even embed this into the merging process. I hope folks who have set it up for Warehouse could shed some light on how it's done.

[dukecat0]

@webknjaz Is it possible to create a new translation project under pypa on weblate?

Probably yes. But I don't have such access. That's why I've tagged @di and @ewdurbin earlier — they should have a better answer to how this could be implemented.

Okay. Thanks

[dukecat0]

I think the Weblate bot (integration?) is able to generate those files if set up properly. My understanding is that we'll need to generate them often or even embed this into the merging process. I hope folks who have set it up for Warehouse could shed some light on how it's done.

So probably we should wait someone answering this before we proceed to the next step.

[ewdurbin]

@pypa/packaging-user-guide-editors @ewdurbin @di @pradyunsg do you think it'd be possible to use Warehouse's Weblate for this? I think the configuration pointers are present here https://docs.weblate.org/en/latest/devel/sphinx.html.

I think we could add another component under the pypa project on weblate, yes. I'll contact them to ensure that would be OK.

[dukecat0]

@pypa/packaging-user-guide-editors @ewdurbin @di @pradyunsg do you think it'd be possible to use Warehouse's Weblate for this? I think the configuration pointers are present here https://docs.weblate.org/en/latest/devel/sphinx.html.

I think we could add another component under the pypa project on weblate, yes. I'll contact them to ensure that would be OK.

Thanks!

[dukecat0]

@ewdurbin Could you add another component under the PyPA project on Weblate, please? The template of translation is located in locales/messages.pot.

[pradyunsg]

The template of translation is located in locales/messages.pot.

Let's move the generation of this into a GitHub action and stop checking this file into the version control -- the output of this is purely deterministic, and checking it in doesn't really have any direct benefit. And, it's likely a merge conflict honeypot, which... isn't ideal either.

[webknjaz]

@pradyunsg I'm pretty sure it needs to be checked in because Weblate is supposed to pick up the phrases from it per my understanding, I'm pretty sure Warehouse works like this.

[ewdurbin]

https://hosted.weblate.org/projects/pypa/packaging-python-org/ has been created. I'd like to ask for one or two folks involved in managing the translation to create accounts on weblate and share their usernames here so I can add them to administer the component.

[pradyunsg]

I'm pretty sure it needs to be checked in

Okay, that sucks. For starters, it doesn't change that we'd need the same automation -- but it'll instead ensure that it's properly generated on each revision instead of just generating it.

It's also a pretty bad state of "updates will need more than just changing the text" in our workflows IMO since it eliminates easy GitHub-UI only changes as well. As an easy example, we'd no longer be able to take GitHub UI driven typo fixes, which... is pretty bad IMO. And, this overhead would likely result in me being significantly less likely to actually write/update the content here myself -- admittedly I haven't done much so we're not losing out on much here, but that might change if other more-active contributors feel similarly.

[webknjaz]

@pradyunsg

Okay, that sucks. For starters, it doesn't change that we'd need the same automation -- but it'll instead ensure that it's properly generated on each revision instead of just generating it.

I think we could come up with some solution pushing the updates to GH automatically, on PR merge, for example. Also, not having the extracted strings in main up-to-date shouldn't be a big deal, we could make sure to update it periodically for starters.

@ewdurbin

I'd like to ask for one or two folks involved in managing the translation to create accounts on weblate and share their usernames here so I can add them to administer the component.

@anxolerd and I have the same usernames as on GitHub, we both worked on the Ukrainian translation of Warehouse. I guess we'd need somebody from a different language background added later.

[dukecat0]

@webknjaz @pradyunsg Is it possible for us to update messages.pot automatically by Github Action when merging the PR?

[webknjaz]

That's what I was thinking

[dukecat0]

@webknjaz I think a better solution would be opening a new repo (probably called packaging.python.org-l10n) for translations, so the new repo will receive changes in packaging.python.org and update messages.pot constantly. Just like python docs.

[webknjaz]

I considered it but I don't see many problems with having a single repo. If it's autoupdated periodically, separately from PRs, it shouldn't cause any disturbance.

[dukecat0]

So there would be a lot commits from Github Action (probably I should set it to update automatically every three/four days so there won't have so many commits), is this acceptable for this repo? :)

[ewdurbin]

webknjaz and anxolerd users on Weblate have been added and should have administrative control over the whole PyPA project on Weblate. @webknjaz and @anxolerd please do not modify settings for the warehouse component or glossary without consulting the pypa/warehouse issue tracker.

I'm going to unsubscribe from this thread now. Please mention me again if there is something I need to do.

[webknjaz]

So there would be a lot commits from Github Action (probably I should set it to update automatically every three/four days so there won't have so many commits), is this acceptable for this repo? :)

Absolutely. Note that using a pre-populated GITHUB_TOKEN secret will not generate any events on GitHub meaning there will be no test runs triggered and no GitHub Apps will react to those commits.

[dukecat0]

Thanks for answering this!

[webknjaz]

@meowmeowmeowcat we need to change the automation to produce paths without ../ in front of the collected strings: this breaks links from Weblate to GH currently (because it removes the segment with the branch name from URLs).

[dukecat0]

@webknjaz Could this be fixed in Weblate settings?

(Something like "Repository Browser")

[rffontenelle]

Hey there. Thanks for the initiative of internationalizing packaging.python.org guide. I'd like to make a suggestion:

While looking for instructions on building translated docs locally, I notice that p-p-o info page on Weblate seems to have exact info as Warehouse component. Not sure if that is a project-wide info, but would be nice to adapt p-p-o info page to be more useful for those localizing p-p-o.

Also, the info has RST syntax (should I take this to Warehouse?) but only Markdown is accepted, so I recommend writing p-p-o's instructions in Markdown.

[webknjaz]

@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?

[webknjaz]

@meowmeowmeowcat if you inspect the URLs in <a href="..."> with DevTools, you'll see that the branch name is included. One example URL is https://github.com/pypa/packaging.python.org/blob/main/../source/overview.rst#L61. But because of /../, it gets normalized as https://github.com/pypa/packaging.python.org/blob/source/overview.rst#L61 which is broken. The only proper way to fix this is to update the pot file not to contain ../ in front of each reference.

[dukecat0]

@webknjaz I've checked some other docs and they didn't remove the ../ in front of each reference, but they still work properly. Therefore, I think this could be fixed in settings.

The only proper way to fix this is to update the pot file not to contain ../ in front of each reference.

Also, I can't remove../ because the messages.pot is located in locales/, which means that it must use ../ to get the text in the docs.

[dukecat0]

Could you please try to change the original one in Repository Browser to https://github.com/pypa/packaging.python.org/blob/{{branch}}/source/{{filename}}#L{{line}}?

If it's not working, I will try another method. :)

[webknjaz]

I guess I could add that /source/ chunk but it just looks like a weird workaround rather than a proper solution.

[webknjaz]

btw Warehouse doesn't have ../: you can see it in https://github.com/pypa/warehouse/blob/main/warehouse/locale/messages.pot.

[dukecat0]

I guess I could add that /source/ chunk but it just looks like a weird workaround rather than a proper solution.

I agree. However, let's use this solution first until we find a better solution for this.

[dukecat0]

btw Warehouse doesn't have ../: you can see it in https://github.com/pypa/warehouse/blob/main/warehouse/locale/messages.pot.

Oh, I see. I think they are using pybabel for extracting messages so they can do this.

[dukecat0]

@webknjaz I've found a solution:

By putting the messages.pot in dir ./, and the .pot won't have ../ anymore.

Example:

#: source/guides/distributing-packages-using-setuptools.rst:95
msgid "For an example, see `README.md <https://github.com/pypa/sampleproject/blob/master/README.md>`_ from the `PyPA sample project <https://github.com/pypa/sampleproject>`_."
msgstr ""

I think this is not the best way as it may affect the .po files we have translated.

And I can't find another solution except for this and changing the Repository Browser. :(

[dukecat0]

@webknjaz Please test this out: https://github.com/pypa/packaging.python.org/blob/{{branch}}/{{ filename|dirname }}#L{{line}}

[webknjaz]

I currently injected /locales/, will address this later then.

[dukecat0]

@webknjaz Could you explain more for injecting /locales/?

[webknjaz]

@meowmeowmeowcat it's the same as your suggestion to add /source/ but is more correct technically because the path is relative to the pot file.

[dukecat0]

Oh, I see. :)

[webknjaz]

@rffontenelle @meowmeowmeowcat looking at your translation attempts I must urge you not to translate references. I saw some translations changing the text in places like

`some ref`_

But this sort of ref is not just a rendered text, it's also bound to the link somewhere in the document that looks like

.. _some ref:: https://...

And changing the ref in one place will break this connection making sphinx incapable of finding the reference target.

Instead, I suggest using an explicit syntax for separate anchor text and the reference identifier that would look as follows:

`TRANSLATED TEXT HERE <some ref>`_

[webknjaz]

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.