search

nodeschool / organizers

A discussion repository for nodeschool organizers
251 stars 59 forks source link

Let's translate ALL THE THINGS! #64

Closed max-mapper closed 8 years ago

max-mapper commented 9 years ago

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:

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

Ideas? Feedback? Comment below!

sotayamashita commented 9 years ago

@maxogden Thanks.

nizaroni commented 9 years ago

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 commented 9 years ago

@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 commented 9 years ago

I must have stored the LANG idea in my subconscious after reading rvagg/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. :fearful:

max-mapper commented 9 years ago

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

nizaroni commented 9 years ago

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 commented 9 years ago

@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. :+1:

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 commented 9 years ago

@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 commented 9 years ago

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 :smile:

pdjota commented 9 years ago

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 commented 9 years ago

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

linclark commented 9 years ago

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 commented 9 years ago

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 tdd@tddsworld.com

nizaroni commented 9 years ago

@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 commented 9 years ago

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 tdd@tddsworld.com

linclark commented 9 years ago

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 commented 9 years ago

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 tdd@tddsworld.com

a0viedo commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

kosamari commented 9 years ago

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 commented 9 years ago

I am working on a completely translated workshopper here: https://github.com/rvagg/workshopper/pull/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 commented 9 years ago

I just created a PR for adventure to add i18n options there: https://github.com/substack/adventure/pull/7

martinheidegger commented 9 years ago

learnyounode and workshopper - done :dancers:

a0viedo commented 9 years ago

You're awesome @martinheidegger! :tada:

mikeal commented 9 years ago

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

Sign up here https://github.com/iojs/website/issues/125

tdd commented 9 years ago

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 commented 9 years ago

Hey guys,

FYI, the status of g11n and FR L10n:

Infrastructure

Workshops

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 commented 9 years ago

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 commented 9 years ago

:+1: 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. https://github.com/sethvincent/javascripting/issues/64

rvagg commented 9 years ago

@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 commented 9 years ago

Hey guys,

A few thoughts I have on this:

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 commented 9 years ago

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

martinheidegger commented 9 years ago

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

a0viedo commented 9 years ago

@martinheidegger you're awesome :tada:

tdd commented 9 years ago

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 :tada:, as this will allow me to contrib FR to javascripting very, very soon. This was the only language-related workshop that lacked FR :wink:

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

martinheidegger commented 9 years ago

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 commented 8 years ago

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