1315811 - Add ability to detect when DOM nodes are localized

Status: RESOLVED FIXED

(L20n :: JS Library, defect)

Description

[Matjaz Horvat [:mathjazz]]

https://github.com/l20n/l20n.js/blob/master/docs/html.md#the-javascript-api says:
"The first time all DOM nodes are localized, the document.l10n.ready promise will resolve."

It turns out no such promise exsists.

Comment 1

[Zibi Braniecki [:zbraniecki][:gandalf]]

I remember you had an opinion on this :)

Comment 2

[Staś Małolepszy :stas]

First of all, sorry about the inaccurate docs.  The reason why that promise doesn't currently exist requires some explanation.

There might be many Localization objects in a single document and we don't know how many there are up-front (XBL or web components might add more).  For this reason we can't have a single global promise resolving when all Localizations finish doing their thing — we don't know what "all" means.

It is still possible to check the 'main' Localization status with document.l10n.get('main').interactive but that resolves as soon as the first language has loaded and not when the DOM has been translated into it. Also, the API for this could be nicer.

Good news is, I'm currently almost done with a refactor of document.l10n (bug 1316083).  After it lands, document.l10n *will be* the main Localization object, so the equivalent of the example above will be document.l10n.interactive.then(..) and it should be easier now to add document.l10n.ready with the semantics described in comment 0.

Comment 3

[Staś Małolepszy :stas]

Attachment: Pull request

Here's a very straight-forward way of doing this.  It's a bit manual.  An alternative would be to pass a runtime-specific function to the constructor and  set this.ready to the return value of the function.

document.l10n = new DocumentLocalization(requestBundles, createContext, function() {
  this.ready = documentReady().then(() => { 
    this.connectRoot(document.documentElement);
    this.translateDocument();
    window.addEventListener('languagechange', this);
});

Would you prefer that?

Comment 4

[Axel Hecht [:Pike]]

Comment on attachment 8813346 [details] [review]
Pull request

We need to return the promises from translateDocument so that we only resolve .ready once all language fallbacks are done.

There's an interesting race condition, should we start observing language change right away, or after the last fallback?

I think it'd be good to do it right away to make sure we're not leaving old languages behind. But should we cancel fallbacks if we're seeing a language change in the middle? Or does that not matter?

Comment 5

[Staś Małolepszy :stas]

(In reply to Axel Hecht [:Pike] from comment #4)
> Comment on attachment 8813346 [details] [review]
> Pull request
> 
> We need to return the promises from translateDocument so that we only
> resolve .ready once all language fallbacks are done.

My bad, thanks for catching this.

> There's an interesting race condition, should we start observing language
> change right away, or after the last fallback?
> 
> I think it'd be good to do it right away to make sure we're not leaving old
> languages behind. But should we cancel fallbacks if we're seeing a language
> change in the middle? Or does that not matter?

We don't have means right now to cancel fallbacks.  As soon as we call translateDocument(), it will localize all element using the full array of language bundles from the initial requestBundles.  If a language changes before this initial translateDocument finishes and we intercept it, it will start a new translation using the updated array of bundles.  In the worst case scenario (with many fallbacks in both cases), these two translation runs might alternate and step on each other's shoes.

I think we should start listening for languagechange only when ready() resolves in order to avoid even a remote risk of non-deterministic behavior.  I assume it's rather rare for the language to change at all anyways.

Comment 6

[Axel Hecht [:Pike]]

Comment on attachment 8813346 [details] [review]
Pull request

r=me.

I think we want a follow-up bug to avoid being deaf for language changes while we translate the first time around. And in that bug figure out how to block concurrent language switch requests.

Comment 7

[Staś Małolepszy :stas]

Landed in l20n.js: https://github.com/l20n/l20n.js/commit/9ed0637675573c70fe5a6970489f0fa98304cf32

Comment 8

[Staś Małolepszy :stas]

https://hg.mozilla.org/projects/larch/rev/48fcc7fe4e16d0c7e233d5d94b4732b99b91c136
Bug 1315811 - Add document.l10n.ready. r=Pike

Comment 9

[Staś Małolepszy :stas]

(In reply to Axel Hecht [:Pike] from comment #6)

> I think we want a follow-up bug to avoid being deaf for language changes
> while we translate the first time around. And in that bug figure out how to
> block concurrent language switch requests.

Filed bug 1319797.  Marking this bug as fixed.