Update on L10n API work

[Zibi Braniecki]

Dear Gaiaers!

Starting from the current Gaia cycle Stas Malolepszy and I (overseen by Vivien) took the lead over the new Localization module in Gaia.

We started by landing a major refactor of the code in l10n.js [1], and now we're cleaning up the way apps use some of the API methods of mozL10n [2].
We looked at virtually all Gaia apps and audited the way they interact with mozL10n during startup and later.

In the process we identified a number of API cleanups that we'd like to complete within 2.0 cycle.

The API has grown pretty organically so far, and many methods are either overlapping, redundant, encourage writing dirty code or are potential vectors of attack. Some of the startup code for runtime l10n can also result in race conditions.

We identified a list of changes that we intend to land very soon, and we'd like to encourage you to think of how it will fit into your work and provide us feedback and comments.

Two major changes are:

## clean up the events emitted by mozL10n [https://bugzil.la/1000806]
you will gain a consistent set of events and helpers that you can use to bootstrap your code depending on l10n, on DOM interactive or combination of both.


## use Mutation Observers to localize nodes that are inserted into the DOM dynamically [https://bugzil.la/992473]
you will not need to use mozL10n.translate -> Mutation Observer will automatically translate nodes and fragments injected into DOM.
you will be able to edit data-l10n-id of a node and mozL10n will add translation, remove translation or retranslate accordingly.


This will make the L10n API cleaner and more consistent. It will also significantly simplify our work in the next cycles, since more of your work on DOM localization will be handled via our API and we will be able to extend localization capabilities of the code without changes in apps.



Many smaller changes are in works:

### separation of mozL10n.ready and mozL10n.once [https://bugzil.la/993188].
This has already landed and allow us to simplify bootstrap code and reduce unnecessary memory retention.


### introduce so-called DOM overlays which allow localizers to use text-level semantic elements in the translations safely without the fear of touching innerHTML; as a developer, you should never do node.textContent = or node.innerHTML = anymore - [https://bugzil.la/994357]


### phase out most of the usecases of mozL10n.translate and mozL10n.localize.
we will rename mozL10n.translate to mozL10n.translateFragment and leave it for edge-cases (you know who you are), but most of the current use cases will be covered by the MutationObserver
same goes for mozL10n.localize. We will clean it up and rename. Most use cases will be covered by the MutationObserver [https://bugzil.la/994519]


### remove .dataset and .style attributes from localizations; they don't belong there and they introduce risks of layout regressions when locales change - [https://bugzil.la/994290]


### enable pseudo-locales in development builds in order to make localizability testing easier for developers and QA people (it's like English, but different!) - [https://bugzil.la/900182]


### remove en-US content from HTML; the reference version is kept in *.en-US.properties files anyways - [https://bugzil.la/812993]
you should stop writing your en-US strings in source HTML files.
reasons: it's confusing, we're using en-US.properties anyways on buildtime,

### unify MockL10n to be able to find race conditions related to l10n reliably. [https://bugzil.la/1004973]


### remove inline localizations. This is overoptimization that significantly increases l10n bootstrap complexity without any performance or UX benefit [https://bugzil.la/994370]

We hope you'll like the changes and it should help us get more consistent, cleaner code.
Ask questions, post feedback and CC us (:stas and :gandalf) in bugs where you currently work on L10n API related code that you think might be affected.

Cheers,
stas & zb

References:
[1] https://bugzilla.mozilla.org/show_bug.cgi?id=914414
[2] https://bugzilla.mozilla.org/show_bug.cgi?id=1000593