Internationalize Friendlycode #163

Merged
merged 37 commits into from Jan 16, 2013

Conversation

Projects
None yet
3 participants
Contributor

toolness commented Dec 7, 2012

Here I have implemented a simple, quick solution to bootstrap localization for Friendlycode.

Goals of the bootstrapping:

  • Allow contributors to start localizing ASAP without blocking on us to "perfect" localization.
  • Potentially allow contributors to provide better copy for certain components, such as e.g. the overly-technical HTML/CSS help that was scraped off MDN, by contributing to the en localization.
  • Start with an extremely simple localization infrastructure: just key-value pairs, no initial support for pluralization, gender, or RTL languages. Evolve as needed, preferably without too much churn (e.g., constantly forcing contributors to re-localize the same content).
  • Allow contributors to provide feedback on the localization of an app so we can solve any problems sooner rather than later.
  • Use a simple but flexible data format for the localization that can easily be converted to whatever interchange format we end up using, be it .po files or .properties files or something else entirely.
  • When possible, use other abstractions that allow us to decouple each component of the localization pipeline from one another, allowing us to replace parts with more powerful alternatives as needed.

Ultimately the initial solution involved the following pieces:

  • Use the tiny requirejs i18n plugin and its i18n bundle convention to access localization data in the product's source code.
  • Create "stub" root i18n bundles in the product's source code that provide default data for the localization, "scraping" content from existing code/data files as necessary. This allows both for friendlycode to continue to minimally operate from flat files (without requiring a special server or build step) and also for a simple build-i18n.js script to scrape and generate initial source data for localization tools to consume.
  • Create a html-to-i18n-bundle.js module that converts slowparse's HTML error templates into the JSON format expected by requirejs-style i18n bundles. This effectively "scrapes" the templates, providing initial source data for localization tools to consume.
  • Create and document a tiny inline-l10n.js module that preprocesses HTML templates in friendlycode and outputs HTML templates with localized content. It can also "scrape" the templates and provide initial source data for localization tools to consume.
  • Create and document a simple localization editor, ghetto-l10n, which takes the output of build-i18n.js and allows contributors to easily localize content and quickly see the results of their work.

toolness added some commits Dec 3, 2012

Internationalized slowparse-errors.
This is sort of weird and inefficient right now because we convert
from HTML to an i18nbundle and back again. However, in production
builds, we will be replacing the 'nls' paths with pre-built bundles
anyways, so only one direction will be computed in production.

Ideally we might want to move all this i18n stuff into slowparse,
though, and just couple slowparse to requirejs.
Contributor

toolness commented Dec 7, 2012

@stenington, do you think you could take a quick look at this?

@ghost ghost assigned stenington Dec 7, 2012

Contributor

stenington commented Dec 10, 2012

I think the code looks good, but there are so many moving parts it's pretty daunting. Maybe provide some information in the README about the i18n approach, and how people can provide localizations if they want to?

I tried to hand-localize a few strings just to make sure it worked, but I ran into a lot of trouble. For example, my understanding is that build-i18n.js should give me the initial localization data to start with, but when I run it I get

$ node build-i18n.js 
{}

I'm not sure if there's a bug, or if I'm supposed to be passing some arguments or something.

Contributor

toolness commented Jan 3, 2013

Whoa, that is definitely odd--running what you did above should indeed give you a nice hearty JSON blob with tasty localization strings.

I wonder if it's related to the rather wide-open version requirement for requirejs in package.json... What does your node_modules/requirejs/package.json say its version is? Mine is 2.1.2.

Contributor

stenington commented Jan 4, 2013

2.0.6... Looks like requiring 2.1.x fixes it.

Contributor

stenington commented Jan 4, 2013

@toolness clarified for me that hand-localizing friendlycode is kind of out of scope for this pull. Integration with the ghetto-l10n thing actually happens by hacking the require config to point the various */nls/ paths at an entirely different url that serves the i18n bundles, and build-i18n.js is script that extracts data in a way that ghetto-l10n needs.

I think this is fine, although it's worth noting that if friendlycode is meant to be localizable by itself, more work may need to be done (instructions on how to do it in the README at the very least). Also, build-i18n.js might make more sense in the ghetto-l10n project rather than being a utility here.

Contributor

cmcavoy commented Jan 14, 2013

Hey, @andrewhayward was looking for something to work on, so I asked him to take a look at this code.

Contributor

toolness commented Jan 15, 2013

Actually, I am going to work on this a bit more today, by documenting it better and moving ghetto-l10n specific stuff (like build-i18n.js) out of the repository. Hold on a bit, @andrewhayward, this will all be less confusing soon!

Contributor

toolness commented Jan 16, 2013

Ok @stenington, I did some refactorings to make this stuff hopefully easier to understand, and also turned build-i18n.js into a really simple tool for localizing stuff w/o any other prototypey tools like ghetto-l10n. Instructions for doing this are now in the README: https://github.com/toolness/friendlycode/tree/i18n#localization.

While I was at it, I also made sure that the localization stuff works w/ optimized builds, and added Travis CI integration, which runs the qunit test suite on unoptimized and optimized builds, as well as some other random shit.

Contributor

toolness commented Jan 16, 2013

I'm pretty confident that this code doesn't affect the stability of the software, and it's easy to change anything that anyone has a problem with after it lands. It also doesn't tie us to a particular l10n strategy--all it does is add a basic lightweight infrastructure for using key-value localization, and it doesn't even commit us to a particular interchange format like .po or .property files (contributions made in the form of requirejs i18n modules can easily be converted to such formats if/when we decide on them).

As such, this pull request was designed to be something we can quickly iterate on--not something that forces all our projects on a path that we can't back away from, that we need to fear landing until representatives from other projects have given it their blessing.

The fact that l10n touches virtually all parts of the codebase means that it's very hard to keep from bit-rotting as other changes are introduced into the project, so I'm going to merge this now and any changes we decide on after evaluating the changes here can be addressed in subsequent commits.

toolness added a commit that referenced this pull request Jan 16, 2013

Merge pull request #163 from toolness/i18n
Internationalize Friendlycode

@toolness toolness merged commit ca0b19d into mozilla:gh-pages Jan 16, 2013

This was referenced Jan 17, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment