Let's translate ALL THE THINGS!

[max-mapper]

Hey @nodeschool/owners, I need your help making workshop translations better!

I've recently hosted events in Taiwan and Japan, and while we were able to come up with an okay system for translating the main website, we still don't have a good system for translating the workshoppers.

The current solution is to fork learnyounode and publish a translated version to npm called e.g. learnyounode-zh-tw or learnyounode-jp.

This isn't a very good solution though as it requires forking, and that means it adds a ton of maintenance overhead. For example, if learnyounode gets a bugfix then that bugfix will have to get manually applied to all of the forks. That is not very nice!

Some other issues I've run in to:

• neither workshopper nor adventure have built-in translation support
• Some workshoppers need to get upgraded to use the latest workshopper, for example levelmeup uses [email protected] but it needs to get upgraded

I'd like to propose a solution, which is to add a feature to both workshopper and adventure that adds a new menu when you first run the workshop that lets you choose your language. So when you run learnyounode the first time you will get a list of languages, and you select the one you want, and it sets that in config somewhere and doesn't have to ask you again (unless you specifically open up the language selection menu again by running e.g. learnyounode language or something).

Also we shouldn't fork anymore, we should instead just store all of the different translations in the original workshopper repository. For example, we currently have a problems folder, and in both workshopper and adventure you can specify the problems path, but we should add a new feature to both of these that lets you pass in a map of multiple languages and multiple paths to problems folders in different languages, like problems-en and problems-jp.

So, I need all of your help! Here's a big TODO list. If you want to work on one of these, declare it in the comments.

TODO for making translations awesome

• upgrade levelmeup to latest workshopper
• add multi-lang support as described above to workshopper
• add multi-lang support as described above to adventure
• write a beginner friendly guide that explains how to write a new translation for both workshopper and adventure based workshops

Other relevant discussions

• Feature mulit langs for workshopper workshopper/workshopper#51
• https://github.com/jlord/git-it/issues/62

Ideas? Feedback? Comment below!

[sotayamashita]

@maxogden Thanks.

[nizaroni]

I think that we should check some standard environment variable such as LANG to try to default sensibly to a locale. Defaulting to a locale should still write that config so it doesn't have to figure things out again.

We also might want to consider defaulting to English. My reasoning is that having a language menu pop up the first time for every user is an extra step might cause additional friction for people who are doing workshops on their own. Of course this is assuming that people randomly stumbling upon NodeSchool on their own is a thing. It's also possible that not showing language options is overall more friction if more of those users don't speak English. I'm not sure.

In the context of a NodeSchool event I don't think defaulting to a language or not matters because leaders can direct attendees to run learnyounode language to select their language.

I wholeheartedly agree that forking is an undesirable solution to the i18n problem.

[max-mapper]

@khalifenizar good feedback, thanks! I think your concerns about adding friction are definitely valid, but it seems to me like something we should build and test out and see if it ends up adding a lot of friction or not.

[nizaroni]

I must have stored the LANG idea in my subconscious after reading workshopper/workshopper#51. I might be able to do the workshopper bit based on that. I'm trying to make an assessment of what needs to be done. Sadly I'm not enjoying an abundance of free time at the moment. 😨

[max-mapper]

@khalifenizar OH YEA I forgot about that thread. I'll update the original post in this thread to mention it

[nizaroni]

Okay I hereby commit to (slowly) add i18n to workshopper. Community, please feel free use your social powers to pressure me into finishing.

[kushal-likhi]

@maxogden Awesome initiative! maintaining forks for i18n is definitely not optimized, on the other hand built-in i18n support is definitely a path to go. 👍

The seeds in my mind are: that a person will most likely _not_ be using different languages for different workshoppers, and we would also like to promote translations by giving them ideas that they can contribute ;). Also supporting @khalifenizar point we should minimize friction:

Hence would like to propose a path in middle, instead of asking for language on each workshopper level we can ask for language once at system level. The idea is that first time the user runs any workshopper, then we can show the language menu and save the value at a common place in the system.
Then if user runs the same or any other workshopper, the workshopper will see if we have that language set, if Yes then load that or if No then show language menu.

Now there could be a case when the language set is not available in that particular workshopper, then workshopper could prompt something like hey! Your default language "<language>" is not available in this workshopper, feel free to send a pull request with translations in your language to make the workshopper more awesome! Find below the list of available languages in this workshopper, chose one to continue. then for that particular workshopper we have a override language set.

Like this we can minimize friction, What are your thoughts?

[nizaroni]

@kushal-likhi You have a point there about setting the user's language on a system level once, gracefully handling when your locale is not available and nudging the community about translating workshops in their language. My only concern is that there's a big difference in terms of user experience between choosing one of 3 locales (or however many) available for a workshop versus choosing a locale from every locale in existence.

I think we should probably make the language selection workshop-specific for now just to get it out the door and think about global configuration later.

[tdd]

Hey guys,

As a French Node trainer, I certainly would like to see i18n land in workshopper and adventure so we can start L10n'ing the workshops. Although most potential attendees to NodeSchool Paris (for instance) would be okay with reading English material (they're in IT after all), quality French text would ease their learning path, obviously. (Also, the French are notoriously worse at English than many other groups…).

I intend to put in the FR L10n of the website itself, too, I need to get on that. As for the workshoppers, @khalifenizar just committed to adding it, so I won't dup the effort (especially as I'm too busy in the next few weeks) but I'm certainly eager to see this land or, when I have time again for it, offer to help should it be stalled.

i18n: putting the World back in World Wide Web, you know 😄

[pdjota]

Setting an env variable such as LANG=ISOCODE, is something an instructor could easily explain at the very begining of a workshop. Looking forward to the i18n integration. We had to do forks for the Spanish versions of the basic workshoppers.

[eafelix]

Excelent idea!
From Argentina we are doing forks or branches from core modules, for the spanish translation.
100% finished.

[linclark]

I like the idea.

One thought about having multiple problems directories, like problems-jp: with the current structure (at least for workshopper) this would require duplicating the exercise verification code as well, wouldn't it?

We could modify the directory structure so that we could have one exercise.js which handles all submissions, and just the problem.md files are i18n. However, there are some times when feedback to the user is hardcoded in exercise.js. For example, in goingnative there is lots of feedback like " version 2011, 2012 or 2013: not found on system".

For this case, would it make sense to introduce something like po files? For example:

msgid "version 2011, 2012 or 2013: not found on system"
msgstr "versión 2011, 2012 o 2013: que no se encuentra en el sistema"

[tdd]

Hi team,

We certainly need a way to i18n the whole thing, not just parts (so any
content that is user-facing should adapt, I guess).

But please, for the love of all that is holy, not these old, limited PO
files :-) They're clunky, and also don't handle multiple-pluralization
contexts in a unique message (which is what ICU was designed to solve).

When it comes to JS i18n we have a number of solutions available, but at
the very least JSON files would work fine for key/translation storage,
and we could resort to i18next.js or (should we need complex control;
this needs an audit on the corpus to translate here) messageformat.js
for loading and interpolation?

Best,

Christophe Porteneuve
[email protected]

[nizaroni]

@linclark You are right, there are a lot of things to translate and it would be less than ideal to duplicate the verification code. The title and subtitle fields in workshopper configuration should also be localized in my opinion. There is also hardcoded English text inside workshopper itself.

I've used JSON language files before but my second language (Spanish) doesn't have any pluralization edge cases so take that with a grain of salt.

I think that it might be easier just to go with the multiple exercise folders for the first attempt at it and then iterate from there on things like not duplicating the exercise logic. I've realized that the later is going to require an i18n solution that is pervasive through each workshop project. Perhaps the second attempt should lay groundwork in workshopper such that implementers can use whatever language file format and i18n module they want.

[tdd]

Freedom of choice for workshop authors sounds nice, but OTOH if the
NodeSchool community is to put in the effort to translate worskhops
(existing and upcoming), it would be nice to spare them having to learn
a new approach at every turn.

So perhaps standardizing on an i18n tech would be nice. If we wish to
address all CLDR use cases, we need a small software layer anyway. I
would advocate messageformat.js, personally. I know it covers all the
CLDR/ICU use cases. The message format is a bit verbose, but very thorough.

I can try and put up a small PoC with it around, say, learnyounode,
sometimes next week. Would you guys be interested in my doing so?

Christophe Porteneuve
[email protected]

[linclark]

Do we need the capabilities of messageformat? I was using PO files as an example because the last project I worked on used them, but I don't think we need most of the features, like pluralization, etc.

I think we could get away with just having simple string mapping and replacement, e.g:

"version 2011, 2012 or 2013: not found on system": {
  "es": "versión 2011, 2012 o 2013: que no se encuentra en el sistema"
}

which would then be handled like this:

exercise.translate('version 2011, 2012 or 2013: not found on system')

This seems like it would be easier for translators to handle than the messageformat syntax.

[tdd]

It would be easier, for sure. However, we may want to audit the
codebase of the workshoppers, quickly, to see what we'd need WRT
localization. If we don't have complex pluralization (or even
pluralization at all), then definitely a tiny JSON-file-based lookup is
fine :-)

Christophe Porteneuve
[email protected]

[a0viedo]

I agree with @linclark it would be great to have just the problem.md files in i18n. Also, I think that the multiple exercise folder approach is easier now but makes the maintenance a lot harder for, e.g., bug fixes.

[bevacqua]

Something to keep in mind with i18n is the actual code to be written. For instance, I had one participant ask me why his code wasn't passing the verify test yesterday, and turns out he had 'hola' instead of 'hello'. Since the text was in spanish, he just figured he had to write 'hola'.

[eafelix]

I agree with @bevacqua , we have to focus on resolutions and check with a language that is used

[kosamari]

This is something separate from technical concern, but down the road, it would be great to have Tone & Voice guide (i.e https://bufferapp.com/tone-guide) set.
In my experience, especially when multiple members are contributing on localization, these comes in handy when deciding what gets merged.

[martinheidegger]

I am working on a completely translated workshopper here: workshopper/workshopper#74 it is now in a state where I can choose the language (yeah!) and I can get different output but there is still quite some way ahead of me and I fear I will need help in testing this monster :)

[finnp]

I just created a PR for adventure to add i18n options there: workshopper/adventure#7

[mikeal]

Just wanted to let everyone know that we've kicked off localization efforts for io.js.

Sign up here nodejs/iojs.org#125

[tdd]

Hey guys,

Just FYI, in anticipation of our first NodeSchool Paris (at Mozilla Paris, Feb 21, filled-up and with 125% waiting list already…), I'm forking every workshopper (plus workshopper itself) and adding FR translations (and upgrading to latest workshopper when necessary).

So if anyone by sheer random chance is tackling FR just now, get in touch so we don't overlap.

[tdd]

Hey guys,

FYI, the status of g11n and FR L10n:

Infrastructure

• L10n fr + g11n tweaks & upgrades on https://github.com/rvagg/workshopper (resulted in 2.3.1)
• L10n fr + g11n tweaks & upgrades on https://github.com/rvagg/workshopper-exercise (resulted in 2.3.0)
• g11n on https://github.com/rvagg/workshopper-boilerplate (resulted in 1.1.0)

Workshops

• L10n fr on https://github.com/rvagg/learnyounode (resulted in 2.5.0+)
• L10n fr + g11n upgrade on https://github.com/mdunisch/lololodash (resulted in 0.5.0)
• L10n fr on https://github.com/azat-co/expressworks (resulted in 2.0.0)
• L10n fr + g11n upgrade on https://github.com/bulkan/async-you (resulted in 1.0.0)
• temporary FR fork-and-translate of https://www.github.com/substack/stream-adventure (done, published as stream-adventure-fr)
• L10n fr + g11n upgrade on https://github.com/sporto/planetproto (resulted in 0.6.0)
• L10n fr + g11n upgrade on https://github.com/stevekane/promise-it-wont-hurt (pending PR merges and npm version bump)
• L10n fr + g11n upgrade on https://github.com/domenic/count-to-6 (PR under review, then pending npm version bump)

Next in line: learn-generators, makemehapi, kick-off-koa and functional-javascript-workshop.

Most of this work is scheduled for this week.

Then there are plans to backport workshopper's i18n infrastructure to adventure (so translators only need to learn one way to do things, as much as possible anyway…), which lets us L10n javascripting and how-to-node, and perhaps refactor stream-adventure to use the latest adventure so it can be L10n'd as well.

[tdd]

A comprehensive roadmap (at least a to-do list), that I'll update as I go, on the work around NodeSchool workshops and workshoppers: https://gist.github.com/tdd/d7b2b719485cdf87bd5f.

Comments welcome!

[martinheidegger]

👍 Way cool! @tdd I am thinking that instead of translating adventure it might be better to switch materials to workshoppers it terms of constant maintenance Cost. workshopper/javascripting#64

[rvagg]

@martinheidegger & @tdd: two reasons that workshopper has a high barrier to entry than adventure that we can fix are:

1. lack of docs (my fault, obviously, even though I keep on promising them ...)
2. too much boilerplate, I know @tdd has presented a proposal to deal with this but I haven't had time to look at it but in general I agree that there are basic cases that we can make easier

Workshopper 2+ was intended to be way more flexible than the original implementation that came from stream-adventure, which I believe it is, but that flexibility introduces challenges, such as the above, but I believe they are easily addressable and am not at all married to the particular implementation and hope for it to learn and grow from continued use. While I'd like to be able to have input on the changes proposed by others I'm very willing to defer to those who have more energy and time than me to invest in making it better and currently you two are probably at that place.

[tdd]

Hey guys,

A few thoughts I have on this:

• Yes, the split adventure rose out of was about code architecture / codebase layout. It's aiming to be much lighter, and entirely API-driven, where workshopper is more CoC-driven (even if that doesn't show much in the current exercise boilerplate).
• We can aim for reduced boilerplate, but I'm not sure at all this will convert adventure users. We need to discuss this with these few workshop owners once we have a solid story for workshopper, particularly in terms of docs and reduced boilerplate. So these "task deps" can inform the order in which we tackle the to-do list.
• I do agree that closing that rift, producing a single workshopper codebase, would be best wrt maintenance and getting-started paths for workshop authors and translators. The ecosystem is, right now, massively based on workshopper, so evolving this one to make it more palatable to users of adventure sounds like a good course of action.
• Rod, I'm reluctant right now to assume decisional / executive power over workshopper et al. for anything but tiny things. This is still very much your baby. I'd be more comfortable merging a PR when I know you don't take issue with its contents.

Specifically, as a first order of business, I'd love to merge my PR on require('workshopper-exercise/basic') (reduced boilerplate for basic case), then go on upgrading the remaining workshopper-based workshops.

I would then probably migrate former workshop upgrades to the new, trivial boilerplate when applicable, and tackle the docs part of the to-do list, before pitching the result to adventure-based workshop owners, in an attempt to port these over.

Best,

[martinheidegger]

I am working on a API compatibility between workshopper & adventure workshopper/workshopper#106 at some point I will need help testing it but it should allow easy porting of current adventures -> workshopper.

[martinheidegger]

FYI: @sethvincent just kindly merged a PR that added translation to javascripting using workshopper-adventure

[a0viedo]

@martinheidegger you're awesome 🎉

[tdd]

Hey @martinheidegger so lemme get this right: is workshopper-adventure an adventure-API-compatible port of workshopper? To ease in the ports of adventure-based workshops? Or is it something else?

At any rate: awesomeness 🎉, as this will allow me to contrib FR to javascripting very, very soon. This was the only language-related workshop that lacked FR 😉

Do you think this path can be take for how-to-npm, too? that'd be kickass!

[martinheidegger]

Its more a branch than a port really and it is already a PR at workshopper. workshopper-adventure is just a temporary release until we figured workshopper out - to test the system if you will. how-to-npm is a bit tricky to translate (not to port to workshopper-adventure). To my understanding @watilde is working on that.

[martinheidegger]

This issue has been open for too long and needs rethinking. Closing it for now.