Are there guidelines on translating guide.elm-lang.org?

I think guide.elm-lang.org is the best resource for getting into Elm, but currently it’s only in English. If it’s translated into other languages, it would be helpful to introduce Elm to non-English speakers.

Last comment from the core team on this issue seems to be to “it’s WIP so proceed at your own risk while following the license”. There’s already a well-maintained Japanese guide which seems to have followed this advice.

I’d like to know if there was any change to this stance, or some plans for future multi-language support.

I’ve discussed with others in Elm Slack and there were volunteers for some languages (@Bastes for French, @razzeee for German, @harfangk for Korean). If there’s no particular guideline, I’ll consult with other volunteers and the Japanese team for how to proceed.

1 Like

I think it would be nice to have translations, but I just want folks to know that there still may be edits to the guide in the future. So perhaps having a date up front of “this was translated in December 2018, so it may not be fully up-to-date with the source material” would help.

I guess the risk is that the translations end up lagging far behind the English version, but maybe that is better than having no translations at all. I do not have a strong intuition about the options here really.

1 Like

What if the guide had a version, example v1.0.2. It would be easier to know if it’s outdated and then look at the commits and update the translations.

2 Likes

Translations will lag behind the original text, but that’s just how it works. Not everything has to stay up-to-date in sync - just as you’ve released 0.19 without waiting to update all standard libraries.

Still, it would help to have version tags on the guide as @G4BB3R has suggested. It would give nice signposts to easily check whether the translation is up to date or to chunk translation works for different contributors to take up. It doesn’t have to happen regularly - just add a version tag after some commits and some PR merges whenever you feel like bumping it!

So my biggest questions at this point:

  1. I would have assumed it would be the best to integrate it into the guide - just have flags/a dropdown and be able to switch. But seeing the Japanese one, I realize a separate page is also an option. Still I like the integrated one better.

  2. Having been active in some other open source communities, I know that there are translation workflow tool. One of the projects I’m part of has been using https://www.transifex.com/ for years.
    I also tried https://crowdin.com/ at one point, to replace the transiflex integration. Both are free for open source. Most of these can automatically pick up changes in a file on github and feed that file into the translation workflow. Then automatically export the translated files into github.
    So all we would need is to bridge that gap or hope we can find a library that implemented a compatible format, https://package.elm-lang.org/packages/ccapndave/elm-translator/latest/ for e.g. sounds quiet custom.

Elixir School has that integrated style of managing different language versions.

Looking at all the issues and PRs, it looks like it’d need a dedicated project owner to manage it. Plus this approach would require integrating original English guide, too. So I’m reluctant about it. I’m leaning more toward individual repositories like the Japanese guide.

Elixir School has been incredibly helpful for people in Brazil to learn elixir (only 5% of the population speak english, only 1% fluently).

I personally know a few people interested in Elm who speak poor or no english. A Portuguese translation would be incredible.

I strongly agree with the english guide having a version too, as @G4BB3R suggested. In Elixir School there is a version also per lesson, that way is very evident/easy to see what’s outdated where. For example https://github.com/elixirschool/elixirschool/blob/master/pt/lessons/advanced/behaviours.md

This way, is also easy for contributors to make a PR with the translation update of individual markdown files.

I think individual repos would be easier for us to get started and would require less overhead from @evancz and core team.

It sounds like a path is to have translators just make the translations now, with independent repos and hosting. I will not be making edits to the guide for a while. Next time that happens, I can figure out how to make some visible “version number” so people have some way of checking. (Maybe just a date on the cover page.)

I just made a channel called #guide-translation in Slack. I recommend that anyone doing a translation joins the channel. I will ping folks there when changes are coming to the guide and the versioning convention needs to be devised.

Once we have completed translations, we can figure out if there is a way to put them together in a nice way. I do not think that figuring out what that might look like should block the translations though.

7 Likes

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.