Skip to content

New Features (rev 3)

Jump to bottom
Zibi Braniecki edited this page Mar 28, 2019 · 8 revisions

This article lists all the new features proposed for revision 3 of DOMOverlays API.

1. Allow all elements as children in the source

As a developer, I want to use all available HTML elements as children.

<div data-l10n-id="key1">
  <ul>
    <li></li>
    <li></li>
    <li></li>
  </ul>
</div>
key1 = This is a list of errors with
  <ul>
    <li>Bullet 1</li>
    <li>Bullet 2</li>
    <li>Bullet 3</li>
  </ul>

Proposed behavior: Allow for the source to include elements that define what elements can be used in the translation. Recursively nest into them to allow for nested structures.

References:

2. Allow text-level child elments in translations

As a localizer, I want to be able to use text-level elements such as <em> and <sup> in translations even if they are not present in the source.

<div data-l10n-id="key">
  Text which doesn't need italics in English.
</div>
key = Text which needs <em>italics</em> in another language.

3. Do not remove child elements from the DOM

As a developer, I want to be sure that a translation will not remove a child element which is important for the functioning of the UI. For instance, if a broken localization doesn't include the <button>, I still want to be able to rely on the button being present in the DOM.

<div data-l10n-id="submit-button">
  <button id="submit">Submit</button>
</div>
submit = No button here.

Proposed behavior: Child elements from the source are always inserted into the translation. If they cannot be matched to anything in the translation, they're added at the end.

document.getElementById("main-link").setAttribute("href", "https://www.mozilla.org");

References:

4. Overlay elements based on type and position

As a developer, I don't want to have to use data-l10n-name for all functional child elements.

As a localizer, I want to edit the most streamlined version of the markup possible, without attributes which add cruft.

<div data-l10n-id="key1">
  <ul>
    <li></li>
    <li><button id="..." onclick="..."></button></li>
    <li></li>
  </ul>
</div>
key1 = This is a list of errors with
  <ul>
    <li>Bullet 1</li>
    <li><button>Submit</button></li>
    <li>Bullet 3</li>
  </ul>

Proposed behavior: Allow for the source structure to be replicated in the translation and auto-match elements on each "level" based on their type and position.

5. Allow translations to overlay elements in different order

As a localizer, I want to be able to reorder two child elements on the same nesting level.

<div data-l10n-id="key1">
  <a href="https://www.mozilla.org"/>
  <a href="https://www.firefox.com"/>
</div>
key1 = Open <a data-l10n-pos="2">Firefox</a>, which is a <a data-l10n-pos="1">Mozilla</a> product.

Proposed behavior: Localization can optionally use the data-l10n-pos attribute to explicitly match a different elements than it would get assigned based on the order in DOM.

6. Protect opaque child element from being localized

As a developer, I want to be able to insert a child element into a translation whose content may not be localized. This is useful for wrapping child elements which provide extended functionality in translated content.

<div data-l10n-id="key1">
  <menulist data-l10n-opaque="true"/>
</div>
key1 = Always <menulist/> when opening a new tab.

7. Retain the identity of source elements

As a developer, I want to store references to child elements and attach behaviors to them without the localization layer breaking them.

<div data-l10n-id="submit-form">
  <button id="submit">Submit</button>
</div>
submit-form = <button>Submit</button>

Even after multiple retranslations, the identity of the <button> should be the same. The element should not be recreated by the localization layer.

let button = document.getElementById("submit");
button.addEventListener(...);

// Someplace else in the code...
// Button is still a reference to the button in the DOM.
button.style = "...";

Proposed solution: Child elements are re-used rather than recreated.

References:

8. Allow nested localizable elements

As a developer, I want to be able to build nested structures of localizable elements, each with its own data-l10n-id.

<div data-l10n-id="key1">
  <menulist>
    <menuitem data-l10n-id="menuitem1"/>
    <menuitem data-l10n-id="menuitem2"/>
    <menuitem data-l10n-id="menuitem3"/>
  </menulist>
</div>
key1 = Always <menulist/> when opening a new tab.
menuitem1 = sing
menuitem2 = blink
menuitem3 = play a sound

9. Allow asymmetrically nested translations

As a localizer, I want to be able to add more nested children than are present in the source.

As a developer, I don't want to think about all possible permutations of nested elements which may appear in translations.

<div data-l10n-id="key1" data-l10n-whitelist="ul, ul > li"></div>

Translation 1:

key1 = This is a list of errors with
  <ul>
    <li>Bullet 1</li>
    <li>Bullet 2</li>
    <li>Bullet 3</li>
  </ul>

Translation 2:

key1 = This is a list of errors with
  <ul>
    <li>Bullet 1</li>
    <li>Bullet 2</li>
    <li>Bullet 3</li>
    <li>Bullet 4</li>
  </ul>

Translation 3:

key1 = This is a list of errors with
  <ul>
    <li>Bullet 1</li>
    <li>Bullet 2</li>
    <li>Bullet 3</li>
  </ul>
  <ul>
    <li>Bullet 4</li>
  </ul>

10. Allow void elements

As a localizer, I want to be able to use the <element/> syntax.

<div data-l10n-id="key1">
  <img src="logo.png"/>
</div>
key1 = Click on <img/> to go to the next page.

Proposed solution: Use an XML parser.

Status: DROPPED.

References:

11. Minimize churn

As a developer, I want to be able to apply translations, including DOM Overlays, while causing as minimal churn and number of mutations on DOM as possible.

That means in particular:

  • avoid updating attributes when the value doesn't change
  • avoid removing/adding attributes when value does change
  • avoid removing/adding elements when content doesn't change
  • avoid removing/adding text elements when content of them does change
  • avoid removing/adding elements when only order changes

References:

Clone this wiki locally