[OS] Chinese Document Translation

[LeonSong-DM]

Summary

• OS: 7.2.2

Description

Hello,

I have been using this project recently and found it very helpful.

I would like to contribute a Simplified Chinese translation of the documentation to help more Chinese-speaking users learn and use this project.

Before starting, I would like to know:

• Would you be interested in accepting Chinese documentation?
• Is there any preferred structure or contribution guideline for translated documents?
• Should the translation be maintained in the main repository or a separate documentation repository?

I would be happy to help maintain the translation and keep it synchronized with future documentation updates.

Thank you for your work on this project.

[giampaolo]

Ni hao. This has been proposed in the past, but it never went anywhere.

For the record, I recently rewrote the whole documentation, and it is now much better and more complete than before. You can see it here:
https://psutil.readthedocs.io/latest/

I am not sure how this would work in practice. I know Read the Docs supports translations natively, so I imagine we would end up with separate paths such as en/faq.html and zh/faq.html, with translated source files living in the same psutil repository.

At the same time, I am a bit skeptical about how useful this would be, since most browsers can already translate pages on the fly. Which arguable may be even better, since Chinese doc will always be up to date.

Also note that there is now a blog, and that we probably don't want to translate.

Random question: do you know of any other projects that do this? How common is it? For context, my wife is Chinese, and I know English is not very widespread in China. But developers may be a different audience.

[LeonSong-DM]

Thanks for your reply!

I understand your concerns. Here are a few thoughts:

You're right that non-native English speakers can use browser translation tools. However, machine-translated documentation is often difficult to read for technical content, especially for beginners who are not yet familiar with the terminology.

As for open-source projects with multilingual documentation, Kubernetes is a good example of a successful community-driven translation effort.

To avoid adding maintenance overhead to psutil, I could maintain an independent Chinese documentation website that only targets the latest stable release. It would not require any integration with the psutil repository, CI pipeline, or documentation workflow.

If such a translation proves useful to the community, perhaps it could simply be linked from the README or documentation page as an external community resource.

Would that be a reasonable approach from your perspective?

[giampaolo]

I think integrating it into the official doc and repo makes more sense, even if it means more maintainance. But we have to study how to do this in terms of Sphinx first (https://www.sphinx-doc.org/en/master/usage/advanced/intl.html) . Let me release 8.0.0 first (should be soon), but in the meantime maybe you can start working in your own branch as an experiment? I suppose you can:

• move the current .rst files into docs/en
• copy those files into docs/zh or docs/zh-cn (I'm looking at how Kubernets did it https://github.com/kubernetes/website/tree/main/content)
• start translating the docs/zh files

That's gonna be the structure. After that, I guess I'll have to configure Read the Docs to make it multilingual. The flyout menu in the top bottom is supposed to show a selection of languages.

There is one thing I'm not sure about: the blog. Translating that is overkill, since the blog changes more often, so we don't want to translate blog articles, but I'm not sure what's gonna happen if you're on the Chinese version of the site and click on the blog.

Extra: it kind of annoys me that URLs will then be in the form of en/faq.html. I would like there to be faq.html for the english doc, and zh/faq.html for Chinese. But that's probably a Read the Docs (or Sphinx?) thing that we cannot change.

[LeonSong-DM]

That sounds good to me. I'll wait for 8.0.0 to be released and, in the meantime, start experimenting on my own branch with the structure you suggested.

For the blog, I agree that translating every article would probably be too much maintenance. Maybe we can keep the blog English-only and simply redirect Chinese users to the English blog when no translated version exists.

Regarding the URLs, I'm not too concerned about the zh/faq.html part, but if we really want cleaner URLs, I wonder whether we could handle it at the web server level. For example, with Nginx, it might be possible to serve the English documentation at the root (/faq.html) while internally mapping it to /en/faq.html, and keep Chinese under /zh/. Not sure how well that would work with Read the Docs hosting, though. It may depend on how much control we have over the deployment infrastructure.

I'll first focus on setting up the directory structure and translating a few simple pages so we can see how the multilingual workflow feels in practice.