L10nID Object type

[Zibi Braniecki]

As I work with Gaia apps to migrate more of them to L20n API I noticed that a lot of apps need to behave in a polymorphic way when it comes to translation.

Instead of clear element is localized by an entity with ID X, we have a scenario where something may receive an ID or a raw string or maybe an ID/Args combo.

The two common scenario is HTML element translation:

var songName = data.name;

if (songName) {
nameElement.textContent = songName;
} else {
nameElement.setAttribute('data-l10n-id', 'unnamedSong');
}

------------

This of course may happen to Notification, or Bluetooth connection where we may have a name of the device, or want to pass a localized version of the string "unknown device".

Over time, I developed a convention in which I pass an argument of type L10nID which can be one of:

1) 'id'
2) {id: 'id', args: {}}
3) {raw: 'string'}
4) {html: 'html fragment'}

The first is just a shortcut to the most commonly used scenario where you just pass a string with an ID of the entity.

Second is the second most common scenario where you need to pass an id/args pair that will be resolved by L20n.

Third is the scenario in which a raw string is to be used, and fourth is for HTML scenario.

This allows to write easy code like:

function updateTitleField(l10nId) {
var titleElement = document.getElementByid('songTitle');

localizeElement(titleElement, l10nId);
}

function localizeElement(element, l10nId) {
if (typeof l10nId === 'string') {
element.setAttribute('data-l10n-id', l10nId);
} else if (l10nId.raw) {
element.textContent = l10nId.raw;
} else if (l10nId.html) {
element.innerHTML = l10nId.html;
} else {
document.l10n.setAttributes(element, l10nId.id, l10nId.args);
}
}

---------------

This pattern is super helpful as it standardizes code localization and once a developer is familiar with how L10nId object may look like its easy to work with across different code pieces. The localizeElement I usually implement is not full (the 'html' scenario is rarely used) but it works well because it is easily extensible (for templating we could add template arguments to 'html' scenario, or add another one).
On top of that the fact that the string scenario is resolving to entity ID means that the API promotes writing localizable code which is one feature I find very important when designing API's - it should suggest the right solution by making it the easiest.

I started using it across many apps and started thinking about adding it as a helper to l20n.js. While I don't think that there's a value to add a class type because it would just increase memory cost, I think that having such localizeElement in our DOM API would help developers use L10nID approach.

It also means that it will be easier to transition to l10n-id once we standardize, or make any other alternations since the API is more centralized.

What do you think?
zb.