Gluon: Deutsche Dokumentation // Multi-Language Documentation

[yanosz]

Is:

• Gluon's documentation is in English.

Should:

• Gluon's documentation is in German, too

Ideas & Remarks:

• Every now and then I encounter people not speaking English. Gluon's doc is a barrier here, while Freifunk is focussing on transporting knowledge.
• For doing translations it is good to have seperated tracking process. Usually, people doing translations are different from people implementing stuff. It'd helpful to have nice workflow. E.g.
  
  
  
  • Overview: What sections are outdated.
  
  
  • (Ticket?)-based tracking integrated into the release process.
  
  
• Some parts are more revelant than others. I.e. deep dives into development are less relevant - Getting started is very relevant
• Lots of Freifunk-Communities have German docs for Gluon. Joining documentation efforts seems promising.
• IMHO doing translations is an easy way for people to join gluon.

[CodeFetch]

Translate it and make a pull-request, but don't expect Gluon developers to keep the German translation topical.

[rubo77]

Wie müsste man die deutschen Dateien in die Sphinx Ordner Struktur einfügen?

Mit Google translate lässt sich das einfach übersetzen als Start. Oder DeepL.com

[yanosz]

hmm... I guess, that having a user-friendly translation workflow is crucial for keeping the docs up-to-date. I'm convinced, that "Translate it and make a pull-request," is not sustainable.

Given, that you could compare & edit all outdated translation on a single webpage, I'd be easy to get people to help translating the files.

The more work we need to spent on finding outdated translations, comparing translations, fiddling translations into git, the less people will be willing and able to help.

Unfortunately, I wasn't able to find a suitable tool, yet. Mozilla pontoon looks very promising on a quick glance - from the UX point of view, that's what I'm thinking of - (https://pontoon.mozilla.org/) but I don't know, how to integrate it into gluons dev workflow (or if you can integrate it at all).

I think that finding a suitable toolchain is a reasonable first step. I'll keep my eyes open.

[CodeFetch]

Someone who understands Gluon enough to translate the documentation should be able to handle po files. You don't want to reinvent the wheel. Readthedocs supports localization https://docs.readthedocs.io/en/latest/localization.html and so does the Github Wiki engine https://github.com/JustArchiNET/ArchiSteamFarm/wiki albeit both are more kind of a workaround.

[NeoRaider]

In the last Mumble meetings we reinforced our decision that English is the official project language - the docs are in English, and English is the preferred language on the mailing lists and in our IRC channel. We would like contributors outside of Germany to be able to participate as easily as possible.

If someone creates a translation, we can link to it, but it should be clear that it is only a translation, and the English version is the only official documentation.

[rubo77]

https://translate.googleusercontent.com/translate_c?depth=1&hl=de&nv=1&rurl=translate.google.com&sl=auto&sp=nmt4&tl=de&u=https://gluon.readthedocs.io/en/v2018.1.x/&xid=17259,15700023,15700122,15700124,15700149,15700186,15700190,15700201,15700237&usg=ALkJrhj3mhiVaLoiXxtP6PKOSkp2gvJM-Q

😉

[kevin-olbrich]

I don't think, that additional doc langs would help in any topic. To debug Gluon / LEDE / OpenWRT, english is mandatory. Also, most vocabulary / technical terms like server, router, etc. are i18n and don't need to be translated.

Other langs are fine for how-to's or installation guides for the enduser and that is something that local communities should be providing.

[christf]

On Sun, Dec 02, 2018 at 01:48:32PM -0800, Kevin Olbrich wrote:

I don't think, that additional doc langs would help in any topic. To debug Gluon / LEDE / OpenWRT, english is mandatory. Also, most vocabulary / technical terms like server, router, etc. are i18n and don't need to be translated.

Other langs are fine for how-to's or installation guides for the enduser and that is something that local communities should be providing.
What is the quality of the result when applying deepl.com to a given
gluon docs page to translate the content into german?

Is it usable (I think it is not perfect but good enough to be of benefit)?
Can we ask our user base to do this?

If the answer to the first question is yes and the second is no, maybe a
bot can do the translation and keep it up to date?

[bobcanthelpyou]

If the answer to the first question is yes and the second is no, maybe a bot can do the translation and keep it up to date?

A user could use deepl on-demand if a translation is needed, then the translation is up2date, too.

By the way, is a translation by a service like deepl free to use and is it allowed to create public documents with it?

[yanosz]

Reading your suggestions, I've doubts about going one with this issue.

Many comments focus on "how to translate" (service, technical details such as .po files), or which parts not to translate ("english is mandatory"). IMHO this is somewhat missing the point.

My idea is to provide an easy start for Freifunkas, who are not mature in English and who are overstrained by understanding an English text from a non-familar, technical domain. Docs for theses kind of people are usually provided by wikis of different communities (if communities care about onboarding new Freifunkas) and I've'd some people in mind then writing this issue.

And basically the Freifunk-Project is mostly about that: Empowering people to build networks.

Providing a supportive onboarding experience is beyond "use deepl if you want" - its about presenting manuals in an easy to understand way. It's about inviting users to read and understand the docs. Of course, this may include linking machine translated versions of parts of the documentation, but it definitely includes having a landing page that could contain such a link.

Judging by the feedback, I think, that providing this kind of documentation is neither in Gluon's scope nor in the maintainers interest.

In the end, this probably boils down to writing my own docs in kbu's wiki and not proactively sharing or aligning its content.

I guess, that we can close this issue in a few days unless new insights are provided.

[T-X]

I'm wondering whether it might be a good idea instead of discussing a full translation of the current documentation which has grown to quite some size to start with something easier/smaller:

Would it make sense to start with some pretty, multi-language landing page? It could cover some basics of Gluon and translated release notes but would link to the repository, full documentation and contact possibilities for further details and assistance otherwise.

Maybe that would significantly lower the bar already?

Of course, this would need some dedicated and commited people interested in maintaining it.

[rubo77]

I think it is a great idea to provide a German translation...

My suggestion: clone this repo and translate it. When it's done, we can link to it on the starting page of the English Doks.

Finding out changes that have to be translated again is easy by simply monitoring the English Doku Files for Changes with somegit diffcommands

[CodeFetch]

@yanosz Gluon is not Freifunk. E.g. we are hoping to merge with LibreMesh firmware development in a distant future. Gluon will never provide a Freifunk-specific documentation, but of course your suggestion makes sense. A German translation would be great, but also a French, Spanish, Italian... German is the language to start as we have many translators for that. Thus I ask you to change the issue title to something like "Multilingual documentation", please.

[yanosz]

@CodeFetch, well, "Gluon is not Freifunk" is a very delicate, philosophical topic that is completly off-topic. I'm not interested in discussing this on github issues.

Libremesh is already providing an Italian documentation for onboarding. Actually, this it what I'm thinking of. By that, translation is already an issue when thinking about a merger. Changing the title is a good idea in that context.

Please mind, that German docs on Gluon are not Freifunk specific, unless they provide insights different from their English counter-part. Nobody has proposed that so far. Thus I don't understand your concerns.

[kaechele]

It's actually pretty easy to do:

cd docs
make -e SPHINXOPTS="-D gettext_compact=0" gettext
sphinx-intl update -p _build/locale/ -l de

Then edit the .po files in locales/de/ using your favorite PO-file editor (e.g. poEdit).

When done:
make -e SPHINXOPTS="-D language='de'" html

Feel free to take a stab at it.

Having the translations in the main repo is probably not feasible, as they will be outdated and unmaintained in 99% of the cases.
So keeping the translated files in a separate repo and maybe even using a service like Transifex to enable easier translations by the community would be advisable.

[CodeFetch]

@kaechele I don't have a clue how to integrate this into ReadTheDocs. As you seem to understand it, can you please have a look at how to do it and maybe how to use e.g. Weblate or something else that has tight git integration?

[kaechele]

Definitely willing to help here. But I guess that would require me having access to the ReadTheDocs settings.
Weblate or Pootle I can set up as well, but we'd need to discuss whether we want to manually sync in the translation updates or someone does this manually on a regular basis.

[kaechele]

I set up this for testing: https://translate.kaechele.ca
Feel free to use GitHub for login (using Oauth) but don't invest too much time there, as this is my personal test instance and data may go away or things may break without notice.
But please have a look if this is something that we would want to be doing.
Sphinx makes it a bit convoluted by breaking out each section of the docs into a single translatable file.
I'm now looking into piecing together everything to commit that back to the git repository.

[CodeFetch]

Thank you very much! I like it. Weblate has a Github App for CI: https://github.com/apps/hosted-weblate
Can we use this somehow?

[kaechele]

Yes, weblate supports github webhooks natively even when not using their hosted product.
To set it up you'd need administrator access to the repository settings though.

[mweinelt]

I don't have an issue with setting up webhooks for certain events for this project.