Translation of the documentation

[micxer]

Hi there, are there any plans to translate the documentation into other languages? I often face the challenge to explain stuff to my parents and would like to point them at the user documentation. however their English is very basic and they can't follow or understand a technical documentation.

I would volunteer to take part in the german translation but I guess a project of this size will need some infrastructure and a defined process how to track translations and translation progress.

[MaxBogach]

I would volunteer to take in the russian translation.

[TurtleTony]

Love this project, I could help @micxer with german translation if there are plans for it any time soon

[calmh]

As far as I can tell the support for translation in Sphinx (our documentation generator) is substandard. So the first step here would be for someone to figure out a framework for how to do / enable translations technically.

[micxer]

Well I just had a quick look at other projects using Sphinx if any of them are multilingual. And in fact CakePHP is. So there seems to be potential to build on their experience and setup.

[AudriusButkevicius]

Seems it's already supported?

http://www.sphinx-doc.org/en/master/usage/advanced/intl.html

[calmh]

Yeah, by extracting all phrases into PO files and running them through Transifex. But translating documentation by going through a huge list of "phrases", one paragraph each, in alphabetical order, in the transifex UI seems like torture and guaranteed to result in something horrible, possibly pages with every other paragraph translated... I'd have expected something like faq.rst with a faq.rst.sv_SE beside it as an alternative, or similar.

CakePHP do indeed seem to be doing something like that; maybe there's a plugin of some sort, or they're just doing entirely separate page hierarchies per language, we'd need to check it out.

[AudriusButkevicius]

Sure, but you'd be translating all phrases anyway and I think it's fine.
Or are you worried that you need context to translate a given paragraph?

[calmh]

Definitely you need context; also the translation might be materially different, as in JSON examples with different values or comments, different sentence structure suggesting different paragraph breaks, links to other local language docs, different screenshots, etc.

[micxer]

I would also rather go for the CakePHP way and have different sources for the different languages for the reasons @calmh mentioned.

[AudriusButkevicius]

I am not sure how that works, but if you have a docs repo per language, then means updating docs means updating docs in N language folders, then it's a nono

[TurtleTony]

But isn't updating N sources for N languages inevitable @AudriusButkevicius ?
You would think that proper documentation in other languages would require dedicated language documentation rather than automated translation to ensure quality of the translations. You could of course just have placeholders for everything and fill them in with the localized strings. It is however questionable how good the quality of such translations can be and if that would improve or decrease the overall quality of the documentation.

[calmh]

Yeah I have a hard time seeing how we would avoid duplication and the inevitable drift between language versions. The alternative with "phrase based translation" leads to paralysis where we can't fix even typos in the original for fear of breaking all translations.

On the other hand I honestly don't think all the documentation needs translating. It would be good to have a good getting started / introduction / FAQ in every language. (First step would be to make it up to date and good in English...)

More technical stuff like the config reference, REST api reference, etc, which is also what changes most often, I don't think needs translating as urgently. Of course it's always nice to get something in your native language, but anyone dealing with technical resources on the internet will have run into the fact that they'll usually be in English, and be prepared to deal with that...

[micxer]

I agree. My initial idea was to have a translation for the part that's focused at using Syncthing. I would expect someone that is administering a Syncthing instance to have some English skills so there is no need to translate each and every part of the docs.

[calmh]

Anyway. I don't plan on driving this process. Someone who feels strongly about this is welcome to figure out a good system and propose a technical implementation of it. I suspect the other already involved maintainers feel similarly, so as is there are no plans - be the change you want to see in the world. :) (general you, not you specifically @micxer, you just happen to be OP and last responder before my comment.)

[micxer]

I actually planned to provide a PR later on, but the discussion definitely helped to see, where the whole thing should go. "Later" is probably a few weeks from now but there doesn't seem to be a hurry :-)

[AudriusButkevicius]

What I mean is that I don't expect to have to copy a blob of english text into n language directories in hopes that someone will translate it.

[calmh]

No, that would clearly suck.