Preview of the async API: l20n.js for Gaia

[Staś Małolepszy]

Some time ago I started working on the next iteration of the L10n.js API
(3.0) with a clear goal to make all retrieval methods asynchronous. Thanks
to everyone who provided feedback!

Today I'd like to announce something I'd call a beta milestone for 3.0. I'd
like to give instructions about how to test it and ask for even more
feedback!

The new API is very simple. It consist of:

- window.L10n

This is the parent "service" object for localization. It stores the state
of the language negotiation and can create new Localization Views.
https://github.com/stasm/l20n.js/blob/60b25de287424aac0fa1a97f0e7c1ff57b955d20/src/bindings/html/service.js#L5-L9

- document.l10n

These are instances of the View class. There can be many views, for
instance one for each iframe. Views have their corresponding lightweight
contexts which in turn use localization resources stored in the window.L10n
service.
https://github.com/stasm/l20n.js/blob/60b25de287424aac0fa1a97f0e7c1ff57b955d20/src/bindings/html/view.js#L15-L24

You can find the code at https://github.com/stasm/l20n.js/tree/lightweight.
It's a major rewrite of our current library and it might be helpful to view
the diff at
https://github.com/l20n/l20n.js/compare/master...stasm:lightweight.

There are still things that I haven't added yet:

- no buildtime bindings; my branch of Gaia uses the old l10n.js script
for building apps,
- no pseudolocales (should be easy to add at this point),
- no isPretranslated logic (I'm hoping we could remove this..),
- no pendingElements logic for the mutation observer,
- no support for data-no-fetch,
- no support for inline script definitions of resources,
- no method to programmatically change language,
- no FSI + PDI wrapping in the resolver,
- …probably a few more things.

* * *

The new API changes a number of major concepts revolving around the
initalization of the code. Previously, we'd rely on mozL10n.once() and
mozL10n.ready() to initialize the rest of the code. Right now this is not
required, since all API calls are asynchronous. There are also two new
events that can be used by developers: supportedlanguageschange and
DOMLocalized.

On my branch I removed the legacy methods line once, ready or get.
Therefore, it's not possible to use l20n.js in most of Gaia apps today.
One notable exception is the FM Radio app which doesn't use the mozL10n API
at all (well done :). The last commit that works for other apps is:

https://github.com/stasm/l20n.js/commit/964dcadfc72a12b97188909ca869803b40f22528

It implements shims of old events and methods. This can be useful for
testing apps like the Settings app. You can also use my branch at
https://github.com/stasm/gaia/tree/lightweight which has two distinct
commits: one works for all Gaia apps, and the other one (the latest one)
works for FM Radio only.

* * *

I've used Raptor to test performance. Keep in mind that there are a few
optimizations missing at this stage.

https://developer.mozilla.org/en-US/Firefox_OS/Automated_testing/Raptor

Here are the steps I followed:

1. flash a latest engineering build of mozilla-central/master
2. fetch Gaia master
3. make raptor
4. APP=settings GAIA_OPTIMIZE=1 GAIA_DEFAULT_LOCALE=en-US make install-gaia
5. APP=settings RUNS=10 node tests/raptor/launch_test.js
6. git checkout lightweight (or lightweight^ to test Settings)
7. APP=settings GAIA_OPTIMIZE=1 GAIA_DEFAULT_LOCALE=en-US make install-gaia
8. APP=settings RUNS=10 node tests/raptor/launch_test.js

Here are my results for FM Radio:

Master: https://pastebin.mozilla.org/8834261
Lightweight: https://pastebin.mozilla.org/8834260

Lightweight seems to be around 50ms slower today, but I'll continue working
on improving the performance next week.

* * *

Let me know if you any questions or comments!
-stas

[Staś Małolepszy]

I've added two missing pieces today:

On Thu, May 21, 2015 at 4:33 PM, Staś Małolepszy <st...@mozilla.com> wrote:

> There are still things that I haven't added yet:
>

> - no pseudolocales (should be easy to add at this point),
>

Added in
https://github.com/stasm/l20n.js/commit/d784569b8e0588c5cfc6ab3f7d9a80178f609a6e.
I'm happy with how easy this was :)

> - no method to programmatically change language,
>

Added window.L20n.change in
https://github.com/stasm/l20n.js/commit/0e0bea602508bb10a484dfce68fea28b4a82632e
.

-stas

[Staś Małolepszy]

A quick update on the progress of the lightweight branch:

- I added full support for events: fetcherror, parseerror, notfounderror
and resolveerror. All events are emitted by the env to save memory. Events
of type resolveerror get two arguments: the error and the context where it
was caught. There's a special type of event, '*' which is a catch-all for
all other types. I might remove it in the future, but it's been useful for
debugging for now.

- I fixed the parse, format and pseudo scripts in tools/.

- I fixed all lib unit tests in tests/lib (when run in mocha under node).

- I added a few tests for Env in tests/lib/env.

I also started to experiment with other builders than webpack. Zibi found
esperanto, but grunt-esperanto is lacking. There's gobble and grunt-gobble
which are capable of creating esperanto bundles. I have a wip at
https://github.com/stasm/l20n.js/tree/gobble although it looks like some
post-processing might still be required.

I hadto work around querystring.unsecape for unicode unescapes and I think
I found an elegant solution: String.fromCharCode:


I also came across es6-module-transpiler and grunt-es6-module-transpiler.

[Staś Małolepszy]

Accidentally hit Send too soon.

On Sun, May 31, 2015 at 12:19 PM, Staś Małolepszy <st...@mozilla.com> wrote:

> A quick update on the progress of the lightweight branch:
>
> - I added full support for events: fetcherror, parseerror, notfounderror
> and resolveerror. All events are emitted by the env to save memory. Events
> of type resolveerror get two arguments: the error and the context where it
> was caught. There's a special type of event, '*' which is a catch-all for
> all other types. I might remove it in the future, but it's been useful for
> debugging for now.
>
> - I fixed the parse, format and pseudo scripts in tools/.
>
> - I fixed all lib unit tests in tests/lib (when run in mocha under node).
>
> - I added a few tests for Env in tests/lib/env.
>
> I also started to experiment with other builders than webpack. Zibi found
> esperanto, but grunt-esperanto is lacking. There's gobble and grunt-gobble
> which are capable of creating esperanto bundles. I have a wip at
> https://github.com/stasm/l20n.js/tree/gobble although it looks like some
> post-processing might still be required.
>
> I hadto work around querystring.unsecape for unicode unescapes and I think
> I found an elegant solution: String.fromCharCode:
>

https://github.com/stasm/l20n.js/commit/179ddacb292eec713f3b06f6d4f77bd97bb9b718

It would be better to use String.fromCodePoint, but I'm not sure how to
transpile this with Babel.

> I also came across es6-module-transpiler and grunt-es6-module-transpiler.
>

I'll try to see what I can get from es6-module-transpiler and I'll report
back tomorrow.

-stas