Documenting L20n.js

L20n’s JS lib is getting test cases and better documentation to make the code easier to work with and understand.

The JavaScript implementation of L20n is composed of 4 main components:

• context (stas), which handles resource loading, locale fallback and provides an easy pulic API for getting translated strings by identifiers,
• parser (gandalf), which parses the resources downloaded by the context into an AST,
• compiler (stas), which takes the AST and makes it into JavaScript objects which the context can call to get translated strings,
• and finally, HTML bindings (gandalf), which extend HTMLDocument with a default L20n context capable of automatically loading resources specified via link elements.

At this point, we’re almost feature frozen for all of these four components. We’re fixing bugs and making sure the public API is consistent and understandable.

Last two weeks saw us working hard on the context part. We finished a major code refactoring and introduced a robust locale fallback, which I’ll blog about in a future post.

Testing with Mocha

Another important improvement introduced recently was the addition of a full-featured testing framework, Mocha. We’ve written over 200 test cases for the compiler and currently we’re creating more tests for other components. As an nice bonus, Mocha also gives us beautiful test coverage reports.

Mocha is based on node.js, so we had to make a few small modifications to the codebase in order to support it. For example, we make use of node-XMLHttpRequest to mimic the XHR interface available in the browser.

Project page on GitHub

We created a GitHub page to serve as the entry point for all of the docs that we’re writing. Check it out at l20n.github.com/l20n.js.

We use excellent Docco to generate documentation from the comments in the code. See the compiler docs for an example.