Translations: How to go about them?

[mamhoff]

We at OpenTechSchool Berlin like and have used this workshop a lot in the past. As part of our efforts to make our events more inclusive, we'd like to translate it into other Languages so as to provide an entry to programming for people not entirely fluent in the English language.

We also have a Git workshop, in which we have participants make PRs to a not-so-useful repo.

With @bastianalbers we're contemplating running a Git workshop in which we ask participants to create PRs for translating the CSS classes.

Now, there's a range of technical options for including translations on Jekyll pages:

We could use Sphinx, which would require all content to be converted to reStructuredText, but would allow the repo to be translated using Transifex, which is much easier to use for non-Coders in the future.

Another good option would be using https://github.com/screeninteraction/jekyll-multiple-languages-plugin to translate stuff. It fits in better with the Ruby/Rails way of doing things (.yml files instead of .po files for translations, markdown support).

I don't have a strong opinion on using either of these options or even a third one, as long as it allows

• Interaction with the repository using git
• All translations are kept in the master branch (and ideally synchronized so there's a way of knowing whether a translation is out of date).

What do you think? I'd be happy to provide a PR that prepares the repo for being translated.

[lukaszklis]

I love the idea, however I'd wait before implementing this until we agree how to structure the website, so more cities could use it too (new structure, new copy, etc.). Hopefully, it's nothing super urgent…

[mamhoff]

Well, the workshop is scheduled for next sunday (the 29th, a good week from now) - so it is kind of urgent. I should've gotten around to do this much earlier, but I was overworked and then on a much-needed holiday - sorry!

In terms of structure: I don't think having translations around should impede a restructuring of the website. If any of the technical options above impede that in any way, that should inform the decision as to which route to go imo. If anyone can weigh in on this - super welcome!

[lukaszklis]

Ah, okay – I totally misunderstood the point of this issue. :) 👍 for the Jekyll-based approach. @verpixelt @Kriesse – WDYT?

[verpixelt]

I like the Jekyll Approach as well. Does this plugin run locally and produces files ready for production? The site is run on GitHub pages, and only a hand full of plugins work directly on GitHub pages.

[lukaszklis]

@verpixelt I can give it a try tonight and see how it goes.

[verpixelt]

@lukaszklis 👍

[lehmannro]

From how I understand jekyll-multiple-languages-plugin it's an incredibly bad option. You have to replicate every page and translate it piecemeal, while also getting out of sync with the original English version. This is like having multiple stable branches and leads to lots of backporting, which is a huge pain.

If your material won't ever change again (like for blog posts) that might be a feasible option, but curricula change every once in a while.

The other option j-m-l-p seems to offer is Liquid tags for translations, which is even worse: It adds a lot of cognitive burden on understanding the original and won't work with Github Pages.

My suggestion is to look into something with libgettext support. (Disclaimer: I'm the author of that support for Sphinx.)

[lukaszklis]

I'm still not sure about Sphinx, I'll have to read more on the possible integration of it with Jekyll. @lehmannro do you have any experience with doing that?

[mamhoff]

@lukaszklis We use it at OpenTechSchool for example for this course: https://github.com/OpenTechSchool/python-beginners . Also served via GH pages.

[lehmannro]

Yup, built as part of a release and then pushed to gh-pages branch.

I'd be happy if there was something like this for Markdown or Jekyll, but I don't know of anything. The problem is that you really need tool support once we're talking about stuff like lists, code, etc. (which is not just find & replace, but should retain the original block markup.)

It's a pity that localization has been a generally solved problem in software for decades, but not so much for documentation. (Except for Sphinx, which just hooks into that time-tested solution.) But that's another topic...