Godot-docs: Any update about translations?

[Juankz]

Just read on the official documentation:

For the moment, only English documentation is provided. We want to propose localized documentation in the future, but this is not a priority for now.
(...)
When the English documentation is ready for translations, we will provide tools to simplify the work of translators by tracking changes to the English docs that they should translate on their end.

Any discussion going on regarding this? Even if it is low priority, localized documentation can make Godot user base grow a lot. (And is one of the few ways I can contribute, really want to help 😃)

[RiverMesa]

I mean, ultimately nobody can stop you from taking the docs and translating them (in fact, many people would appreciate it!), but the official effort right now is on bringing the English docs up to 100% API coverage (as well as writing as many tutorials and guides in other areas) before looking into non-English translations as part of a project-wide goal.

For what it's worth, one thing I would suggest doing* (or at least trying to do), if you really want to translate the documentation, is to focus on the Getting Started section since that would give you the best "bang for buck" in terms of introducing foreign developers into the engine with the least amount of effort (compared to the other sections of the documentation like the API reference), but even that section is quite expansive.

Plus right now the docs themselves don't support localization, though I'm pretty sure there is Sphinx functionality for this (you can see that when you build the docs manually).

* - I'm not a project manager or anything though, so take my opinion with a bit of salt

[xavierocampos]

In fact I don't know much about GIT so I decided to create a Spanish translation in Wikia where I'm translating the official documentation little by little:

http://es.godotengine.wikia.com

I have looked for collaborators but no one is encouraged at the moment so if anyone is interested I can be contacted to coordinate us.

Although this is a Wiki at the moment the pages I am working on are protected, I think it's the best way to start because if everything is open from the beginning so that anyone can edit it, surely more than one with bad intentions instead of helping would start to spoil the work done.

[vnen]

Heh, there's quite a few (outdated) Spanish translations...

[Juankz]

There are many translators doing things on their own, but lack of organization and review process is a problem. I suggest using Transifex or Weblate.

[Calinou]

I suggest using Transifex or Weblate.

Is either of them usable with something like Sphinx, especially considering we're using Read the Docs?

[RiverMesa]

All other things being equal (which they likely aren't), Weblate would be a good choice considering it's already used for translating the strings in the engine itself, so having people use the same website for both would be convenient.

Then again, that hinges on whether or not such sites are compatible with Sphinx/RTD, like @Calinou said.

[pwab]

As already stated here there is no problem in using gettext. The process of creating language specific files is straight forward and works fine for the godot docs too.

See these links for further information:

• Translating sphinx messages
• RTD docs about multiple languages

[akien-mga]

If someone wants to give a try to setting up i18n in the current docs, I'd gladly review a PR (maybe starting with only one new language and only a few strings translated, to show that it can work). Then I can put up the POT file in Weblate and we can look at how to deploy those things in RTD.

[eon-s]

@xavierocampos I need translation into spanish but I'm waiting for a good way to do it, because that wiki will be really hard to maintain when docs get changes or fixes (also the main old idea to use github), the weblate approach may be ideal if it can keep track of changes on the main documentation.

[akien-mga]

If no contributor beats me to it, I'll add this to my TODO list for March when I start (hopefully) working full time on Godot.

[Juankz]

@akien-mga I'm currently looking into this

[xavierocampos]

I understand all the arguments but each one of us must contribute what we can within our possibilities, and mine are those, so I'm going to continue with the project, although I appreciate the advice.

[Juankz]

@xavierocampos that is fine, in fact I encourage you to continue, once we get to provide a official way for translations you can merge your existing work

[akien-mga]

Continuing the discussion from #1199.

I'm working on setting up a new repository which will hold the POT and PO files, generated manually and synced from Weblate, without impacting this godot-docs repository. The latter will be instanced as a git submodule.

Here's my current proof of concept, with most doc pages removed to get fast builds (otherwise I hit the 15 min build timeouts, which means that I'll have to ask for timeout extensions to the ReadTheDocs admins for all our l10n repos): https://godot-fr.readthedocs.io/fr/latest/ (only the first box is translated)

This is built from this repository: https://github.com/akien-mga/godot-docs-l10n
With language configured to French (so RTD passes the -l fr argument to the relevant commands).

The submodule tracks this testing i18n branch here: https://github.com/godotengine/godot-docs/commits/i18n

It contains some Makefile/conf.py changes (https://github.com/godotengine/godot-docs/commit/08d0dd40d80f4c2bd9acc5454462f4c694d4d011 ) and deletes most content of the repo to get faster builds :)

I was a bit worried about doing out-of-tree builds (the source conf.py is no longer in . but in ./docs, but it seems to work just fine.

I'll now look at how the Weblate process could be, and once I have figured that out I'll add templates for all pages (but classes/ stuff) and create some godot-<lang> projects to get started.

[akien-mga]

So I've discussed it a bit with the Weblate maintainer. The main issue with using Weblate is that it's not really designed for many small POT files, and in our case we'd have 188 of them (one per page - excluding the class reference).

Other projects using Sphinx + Weblate seem to merge all POT files together in a monolithic POT file, and upload only that one in Weblate. Then they split it back in the multiple POT files needed for Sphinx. We could do that too, but it would be a 2.5 MB POT file (i.e. at least 5.0 MB for each PO file once translated).

So I'll look into maybe grouping POT files by folder, so that we can have e.g. step_by_step.pot or 3d_tutorials.pot, reducing the number of Weblate components we'd need to maybe 20 or so.

[akien-mga]

After discussing with a fellow translator (and i18n engineer) used to the systems used by big projects like KDE, GNOME or Fedora, it seems like keeping a single giant POT file for the whole documentation is much better than trying to split it in smaller chunks. Advanced l10n tools like Lokalize can easily filter strings coming from a given page, so that you can focus your work on one page at a time.

So I've went ahead with this setup: https://github.com/godotengine/godot-docs-l10n

Translations can now be done on Weblate like for the editor; new languages can be added by any logged in contributor: https://hosted.weblate.org/projects/godot-engine/godot-docs/

Then for each language, I'll have to create a godot-<lang> project on ReadTheDocs. I'll start doing it for languages which reach a decent completion rate (e.g. 10 or 20%).

So this is fixed :)

I'll open another issue to collect general feedback from translators.