Support docs in multiple languages

[nicoddemus]

I know we had the docs translated to Japanese in the past and, although the initial work seems to have been good, it did not work out because the Japanese docs quickly got out of date with the English docs, and we eventually dropped it.

#6900 (comment) made me think if we should perhaps pursue this again, but this time using a framework/overflow where the translated docs would happen outside/independently of pytest's own repository. I'm sure there are tools to help it out as well (didn't take the time to really look for it though).

[RonnyPfannschmidt]

there are sphinx extensions for i18n that allow doc translation in transifex & co
btw, we miht want to remove the en folder component from the docs

[symonk]

unless its possible to get a relatively automatic translation I think the overhead / maintenance may not be worth it, primarily due to every docs change will require multiple change(s) for contributors in non native languages. An automated solution may be worth trialing (tho they are never really going to be perfect)

[gnikonorov]

@RonnyPfannschmidt - Transifex may work. It looks like they have an open source plan that would be free to use: https://docs.transifex.com/projects/open-source-project

[The-Compiler]

For what it's worth, Why not Valetudo? from another open source project makes some good points why we might not want to do this.

Even with something like Transifex in place, do we realistically have the bandwidth to keep up with translations in multiple languages? Do we have people who can review translation changes? Do the people contributing translations also have enough domain knowledge? Who ensures they stick around long enough not just for an initial translation, but also for keeping the translated docs up to date, for multiple years?

Given pytest's audience (developers, where a lot of communication happens in English even in places where this isn't the natively spoken language): How many people are there realistically who are using pytest, but where a documentation in English (and perhaps automated translation) is a real barrier? And does translated documentation really help that much, because as soon as they want support or have bugs to report, that will need to be in English again anyways?

[RonnyPfannschmidt]

based on he experience wit the japanese versions - i propose we go single language

[webknjaz]

I have a lot of experience with translations on various platforms: ProGit 2 just used PRs on GH, PyPI / Warehouse and PyPUG use Weblate, and many others. PyPUG specifically uses Sphinx. I'm also watching the CPython translation processes occasionally, w/o participating actively.

It's not difficult to set up the infra. The hard part is indeed having translators with long-term commitments. Good news is that if the translation platform is big enough, it can notify people about new strings to translate and changes in the existing ones. Some also integrate automated suggestions based on similar strings in other projects on platforms + suggestions from several translation software APIs.

The hardest part is the initial effort. I think, if a given language had several people ready to participate, it'd be doable. But if it's just one person, that can easily become overwhelming.

P.S. I have a feeling that a lot of the docs bits don't change very often. This is something that is beneficial in this context.

---

On the usefulness: native translations usually allow for lowering the barrier of entry for the newbies. Its biggest impact, in my opinion, is inclusivity. This is why Python does supports Unicode in the syntax even. It wouldn't be as useful to seasoned devs.

[hwhsu1231]

Hello, @nicoddemus @RonnyPfannschmidt @symonk @gnikonorov @The-Compiler @webknjaz

I have published the pytest-docs-l10n project, which aims to translate the Pytest Documentation into mulitple languages. See the announcement post for more details.

If the target language is not supported in the project yet, please submit an issue to request for the new language. Once the requested language is added, you can start translating!