Localizing HTML Elements

Localizing an HTML element is a bit more specific than translating a single string.

HTML Markup

<p data-l10n-id="hello" title="welcome!">Hello, world!</p>
<p data-l10n-id="welcome" data-l10n-args="{user:'John'}">Welcome, {{user}}!</p>

Structured l10n data

For l10n, HTML elements can be represented as objects:

hello: {
    &text: "Bonjour le monde !",
    .title: "bienvenue !"
},
welcome: "Bienvenue, {{user}} !"

Several parts of an HTML element can be translated:

• element attributes such as title, accesskey… could be referenced with a dot prefix: .title, .accesskey, etc.;
• the element content can be seen as a property: innerHTML or textContent. We suggest referring to these properties with &html and &text respectively.

By default, when an HTML element is associated to a string entity, it should be considered to be the text content. In other words, the “welcome” entity description above corresponds to:

welcome: {
    &text: "Bienvenue, {{user}} !"
}

More generally, the & prefix could be used for all element properties but it might be insecure. In fact, maybe innerHTML itself should not be defined in the l10n resource… or if allowed, it should be parsed carefully before being applied to the element.

Concerning the attributes, a white list of all translatable attributes should be defined.

Flat l10n data

When using simpler l10n formats, HTML elements can also be represented as a list of key/value pairs:

hello=Bonjour le monde !
hello.title=bienvenue !
welcome=Bienvenue, {{user}} !

Again, &text is assumed by default here.