Docs: Translate Them

[JacobCoffee]

Summary

What

This serves as a meta-level issue to track translation efforts for the Litestar documentation.

[!IMPORTANT]
Members of the Litestar organization only speak so many languages; we will require verification from multiple proficient/native speakers of the target language to merge the work.

How

We will need to ensure style guides are adhered to including the use of appropriate formalities that are language-dependent. (This will also have to be verified by various speakers of the target language)

[!NOTE]
Also, see the infrastructure changes required below.

Languages

This is the current list of tentative languages to be translated. Other languages can be listed here as they are brought up by anyone seeking to do the translation work in the format of:

- [ ] Language
   - Assigned Translator(s)

• [ ] Turkish
  • @hasansezertasan

Considerations

How do we keep the documentation up to date? One change would require a PR to be opened in all translated languages... At the risk of having fragmented, out of date docs it seems like we should opt for automatic translations or none at all.

Scope

The very nature of fully translating our documentation, especially as it continues to evolve and grow is long running. This issue may not even be the right medium for managing this work, but it at least gives (initial) visibility into the opportunity for others to take it on and help out.

Infrastructure

This work will require changes to existing infrastructure such as CI changes for builds and additional documentation section dependencies.

Some links to help in the set up / investigation of this:

• https://sphinx-intl.readthedocs.io
• https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-documentation-in-different-languages
• https://github.com/sphinx-doc/sphinx/issues/11713
• https://devguide.python.org/documentation/translating/
• https://peps.python.org/pep-0545/

---

[!NOTE]
While we are open for sponsoring on GitHub Sponsors and OpenCollective, we also utilize Polar.sh to engage in pledge-based sponsorship.

Check out all issues funded or available for funding on our Polar.sh dashboard

• If you would like to see an issue prioritized, make a pledge towards it!
• We receive the pledge once the issue is completed & verified
• This, along with engagement in the community, helps us know which features are a priority to our users.

[iRod3s]

Spanish speaker here, ready to help when needed :)

[JacobCoffee]

We will need to update our conf.py with links to target languages

• https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#translating-with-sphinx-intl
• https://pydata-sphinx-theme.readthedocs.io/en/stable/community/topics/i18n.html
• https://docs.readthedocs.io/en/stable/guides/manage-translations-sphinx.html

I don't think this is super maintainable without some type of automation, but it looks like Transifex offers that although quite expensive... hopefully we can get approved via their Open Source program: https://help.transifex.com/en/articles/6236788-open-source-projects

[JacobCoffee]

Looking at various projects, I do not think they manually translate things except core messages? For instance sphinx-doc itself only has one language of any count, Tamil at 99%, but its docs page offers many languages.

• https://github.com/sphinx-doc/sphinx/blob/f4eea669e078cf9fed3f08bd1595f8f758049388/doc/internals/contributing.rst#translations
• https://explore.transifex.com/sphinx-doc/sphinx-doc/

I'm still not understanding the different ways projects are doing this. The FastAPI way for example seems to rely on translation PRs that I would think could become out of date almost instantly, while sphinx-doc for example has no PRs for this and seem to be auto generating but also having transifex work available (?)... pretty lost..

Anyways - This issue will be closed if we cannot figure out a way to automatically do this. The maintenance burden is far to high. Speaking bluntly, while our user count and project size has grown quite a bit but the contributor count has not.

The soonish work towards Litestar v3.0 needs to begin soon, and adding this to our workload when the target audience is getting by as-is for now would just be too much.

However, I am still researching ways to automate this. IF we can do that, this can proceed.

Any ideas welcome.

[JacobCoffee]

https://github.com/sphinx-doc/sphinx/blob/master/.github/workflows/transifex.yml may help

[tuukkamustonen]

Just my 2 cents but whatever you do, please avoid pushing the translation commits to the same litestar-org/litestar repo.

It's so annoying browsing the timeline and realizing everything that has been done is actually translations. A repository which seems very active, is actually full of translation commits and related release note update commits.

It gives the impression that a project wants to pump/fake it's real activity, as that bloat hides away the actual work on features, bugfixes, etc.

Also, English is really the language of the world. Partially/badly/out-of-date translated docs might even do harm over folks contributing to polish the English docs. Translations are a bit of a PR stunt...

In any case, as long as translations live elsewhere and don't pollute the commit history, probably fine.

[JacobCoffee]

I'm going to close this for now. In the research I have done there are a number of potential issues (some with resolutions, some unsure)

Stale Documentation

In searching for automated options, there *were* some, but they were paid or limited. I've reached out and looked about in various places doing large-scale documentation. Here are some from private discussions.

Which seems like it could be remedied by

We use a GHA automation to sync from the upstream. It also adds the flag fuzzy to updated entries for re-review. And when the fuzzy flag is present Sphinx ignores those entries, thus the page always shows the up-to-date content.

Which provides:

• https://github.com/python/python-docs-tr/blob/3.12/.github/workflows/update_doc.yml
• https://github.com/python/python-docs-tr/blob/3.12/merge.py
• https://github.com/python/python-docs-tr/blob/3.12/scripts/translate.py

That seems like something worth pursuing. It will allow us to have translators volunteer in their native or fluent language(s) and on update, they will not be outdated.

However, with the coming advent of Litestar v3.0 our time is going to be really diverted into that.

If someone is interested in doing this in a way that is scalable across any arbitrary amount of languages and in the sense of maintainability (it would require discussion with us to start up to ensure maintenance costs are not high as well) then please feel free to gather your ideas and present them here, in the Discord, or GitHub discussions.

I also have a very strong opinion in favor of what @tuukkamustonen has mentioned as I see other repos do - I too wouldn't want the issue and PR log full of translation-type stuff.

This is closed as Not Planned but it is certainly available for pick up if we find good solutions to the above.