DOM Overlays

This page is about a feature of fluent-dom 0.1.0.

Localization of DOM Fragments

When localizing an HTML document you're likely to encounter two scenarios where the DOM elements may appear in translations:

Mixed fragments

A common example of a localizable phrase in HTML is a case where a link is present in the sentence:

<span>Click <a href="https://www.mozilla.org">here</a> to learn more.</span>

Localizable elements

This is a class of elements in HTML which are called Text Level Semantics. Those are elements that are safe to be added by a localizer and are often required to build correct translations.

A good example of such an element is <sup></sup> used in french honorifics. An English phrase Ms. Fortier will likely be translated to French as M<sup>me</sup> Fortier. In order to handle that, the translation must be allowed to inject some HTML elements.

Solution

fluent-dom supports a safe overlay mechanism which allows localizations to mix HTML into the translation and match it to source fragments.

Example 1:

<span data-l10n-id="key1">
  <a href="https://www.mozilla.org" />
</span>

key1 = Click <a title="Home page">here</a> to learn more.

will produce:

<span data-l10n-id="key1">
  Click <a href="https://www.mozilla.org" title="Home page">here</a> to learn more.
</span>

Example 2:

<h1 data-l10n-id="key1"></h1>

key1 = Bonjour M<sup>me</sup> Fortier.

will produce:

<h1 data-l10n-id="key1">Bonjour M<sup>me</sup> Fortier.</h1>

Safety

DOM Overlays sanitize elements and attributes allowing only a selected list of elements and selected list of attributes to be provided by the localizers.

This allows DOM Overlays to be secure against potentially malicious localization code, while allowing for translations to be more complete.

Whitelisting additional attributes

It is possible for a developer to white-list additional attributes to be allowed for localization on a particular element:

<span data-l10n-id="key1">
  <a href="https://www.mozilla.org" data-l10n-attrs="style" />
</span>

key1 = Click <a title="Home page" style="font-weight: bold">here</a> to learn more.

will produce:

<span data-l10n-id="key1">
  Click <a href="https://www.mozilla.org" data-l10n-attrs="style" title="Home page" style="font-weight: bold">here</a> to learn more.
</span>

Using that shifts the responsibility for the safety of the widget onto the developer.

Limitations

At the moment DOM Overlays do not handle ordering of multiple elements of the same type, and they cannot be used to provide elements from the developer into the fragment, which are not whitelisted as text level semantics.

There's also no way to whitelist additional elements in the fragment the way one can do for attributes.

Those limitations are going to be addressed in the next revision of the API.