{"id":426,"date":"2012-07-16T21:08:53","date_gmt":"2012-07-16T21:08:53","guid":{"rendered":"http:\/\/blog.mozilla.org\/l10n\/?p=426"},"modified":"2012-07-16T21:08:53","modified_gmt":"2012-07-16T21:08:53","slug":"l20n-features-explained-dom-overlays","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/l10n\/2012\/07\/16\/l20n-features-explained-dom-overlays\/","title":{"rendered":"L20n features explained. DOM overlays."},"content":{"rendered":"

(This is a crosspost from my blog: http:\/\/informationisart.com\/8\/<\/a>.\u00a0 Check it out for better code formatting and syntax highlighting.)<\/em><\/p>\n

With L20n’s DOM overlays, developers can amend localized strings with additional non-localizable HTML markup. This improves the separation of content and structure and reduces the cruft in localization files.<\/strong><\/p>\n

When it comes to localizing web content, you\u2019re likely to end up with a lot of HTML inside of your source strings. You might be see markup like <strong><\/code> and <em><\/code>, or simply links to other resources with <a><\/code> tags.<\/p>\n

Consider the following paragraph taken from www.mozilla.org<\/a>.<\/p>\n

Portions of this content are \u00a91998\u20132012 by individual mozilla.org contributors. Content available under a Creative Commons license<\/a>.<\/p><\/blockquote>\n

The HTML code for this paragraph is this:<\/p>\n

\n
 <p><\/span> Portions of this content are \u00a91998\u20132012 by individual mozilla.org contributors. Content available under a <a<\/span> href=<\/span>\"\/foundation\/licensing\/website-content.html\"<\/span>><\/span>Creative Commons license<\/a><\/span>. <\/p><\/span> <\/code><\/pre>\n<\/div>\n
You\u2019ll notice the <a><\/code> tag with an href<\/code> attribute. The href<\/code> is a URL, and it makes this HTML significantly harder to read.<\/p>\n
If we wanted to localize this paragraph, the L20n code for English would look like this:<\/p>\n
\n
 <licenseInfo<\/span> \"\"\"<\/span>  Portions of this content are \u00a91998\u20132012 by individual <\/span>  mozilla.org contributors. Content available under a <\/span>  <a href=\"<\/span>\/foundation\/licensing\/website-content<\/span>.<\/span>html<\/span>\">Creative <\/span>  Commons license<\/a>.<\/span>  \"\"\"<\/span>><\/span> <\/code><\/pre>\n<\/div>\n
The URL will always be \/foundation\/licensing\/website-content.html<\/code>, regardless of the user\u2019s locale. It makes little sense, then, to have it in the source string. The tag makes the string harder to read and increases the risk of introducing an error (e.g., removing a quotation mark or accidentally editing the URL).<\/p>\n
In fact, the href<\/code> attribute is part of the document\u2019s structure rather than its source content, and as such, does not belong in the L20n code at all.<\/p>\n
What if L20n let you skip attributes that are not related to the source content? What if it copied those attributes from the developer-defined code, thus sparing the localizer all the trouble?<\/p>\n
Enter DOM overlays<\/h2>\n
The premise is simple: only localizable source content should live in L20n files. Let\u2019s modify the HTML code and the licenseInfo<\/code> string accordingly.<\/p>\n
\n
 <p<\/span> l10n-id=<\/span>\"licenseInfo\"<\/span>><\/span> <a<\/span> href=<\/span>\"\/foundation\/licensing\/website-content.html\"<\/span>><\/a><\/span> <\/p><\/span> <\/code><\/pre>\n<\/div>\n
The actual content, both source & target, will be injected with L20n code. This way the developer doesn\u2019t have to (although they can) put it in HTML. All that matters is the l10n-id=\"licenseInfo\"<\/code> part, as well as the a<\/code> tag with the href<\/code> attribute defined in HTML. All the rest happens in the L20n file.<\/p>\n
\n
 <licenseInfo<\/span> \"\"\"<\/span>  Portions of this content are \u00a91998\u20132012 by individual <\/span>  mozilla.org contributors. Content available under a <\/span>  <a>Creative Commons license<\/a>.<\/span>  \"\"\"<\/span>><\/span> <\/code><\/pre>\n<\/div>\n
We keep the <a><\/code> tag in the L20n file so that the localizer has control over what is linked and what is not. However, the attributes of the tag are not localizable and thus, are absent in the string. The strings is easier to read, and also harder to accidentally break.<\/p>\n
Matching and reordering multiple overlays<\/h2>\n
L20n\u2019s DOM overlays match HTML nodes by type, name and position. If licenseInfo<\/code> had two <a><\/code> child nodes, their attributes would be matched and copied from the source string in their respective order.<\/p>\n
Consider the following example.<\/p>\n
Welcome to Pancake<\/a>, Sta\u015b<\/a>.<\/p><\/blockquote>\n
The HTML and L20n code responsible for this message might look like this:<\/p>\n
\n
 <p<\/span> l10n-id=<\/span>\"welcome\"<\/span>><\/span> <a<\/span> href=<\/span>\"\/\"<\/span>><\/a><\/span> <a<\/span> href=<\/span>\"\/profile\"<\/span>><\/a><\/span> <\/p><\/span> <\/code><\/pre>\n<\/div>\n
\n
 <welcome<\/span> \"\"\"<\/span>  Wecome to <a>{{ brandName }}<\/a>, <a>{{ $user.firstname }}<\/a>.<\/span>  \"\"\"<\/span>><\/span> <\/code><\/pre>\n<\/div>\n
The <a><\/code> elements are in the same order in the source code and in the L20n code. L20n will thus copy the href<\/code> attribute from the first <a><\/code> element in the source code to the first <a><\/code> element in the L20n code.<\/p>\n
Let\u2019s suppose now that the localizer wishes to change the order of the links. Maybe the grammar requires her to do so, or maybe the register is more (or less) formal in her locale. The expected result would be (translated back to English for the sake of this example) this:<\/p>\n
Hi Sta\u015b<\/a>. Welcome to Pancake<\/a>.<\/p><\/blockquote>\n
Because the order is different, the localizer cannot rely on L20n\u2019s automatching any more. Instead, she needs to instruct L20n which <a><\/code> element corresponds to which one in the source. L20n allows her to do so via the l10n-path<\/code> attribute set on the element, like so:<\/p>\n
\n
 <welcome<\/span> \"\"\"<\/span>  Hi <a l10n-path=\"<\/span>a<\/span>[<\/span>2<\/span>]<\/span>\">{{ $user.firstname }}<\/a>.<\/span>  Welcome to <a l10n-path=\"<\/span>a<\/span>[<\/span>1<\/span>]<\/span>\">{{ brandName }}<\/a>.<\/span>  \"\"\"<\/span>><\/span> <\/code><\/pre>\n<\/div>\n
the second child (descendant of the first generation) of the context node that is an <a><\/code> element.<\/p><\/blockquote>\n
(The context node is the source node that\u2019s being localized, in this example the <p><\/code> element with l10n-id=\"welcome\"<\/code>.)<\/p>\n
In most of the cases, the XPath expression will be very basic and minimal, like in the examples above. The full XPath syntax is supported, however, allowing for more complex matching.<\/p>\n
Lastly, the l10n-path<\/code> is only required when changing order of elements of the same type, like two a<\/code> elements. If you want to change the order of child nodes in a string with one <strong><\/code> and one <em><\/code> tag, you can do so without having to specify the l10n-path<\/code> attributes.<\/p>\n
Privileges and autoextraction<\/h2>\n
The next step is to see if there\u2019s a need to prevent some attributes from being copied. It might be interesting to extend DOM overlays with a mechanism which only accepts whitelisted attributes, or blocks blacklisted ones from being copied from the source strings to the translation. This could be done globally, or even per-entity.<\/p>\n
I also started working on a maintenance script which extracts the contents of source nodes and automatically creates valid L20n code ready to be localized. It supports whitelisting attributes, but generally leaves most of the attributes out of the L20n code. You can find the code on Github<\/a>, but bear in mind that this was more of an experiment and is very much a work-in-progress.<\/p>\n
Discussion<\/h2>\n
Please post your thoughts in the mozilla.dev.l10n<\/a> newsgroup.<\/p>\n","protected":false},"excerpt":{"rendered":"
(This is a crosspost from my blog: http:\/\/informationisart.com\/8\/.\u00a0 Check it out for better code formatting and syntax highlighting.) With L20n’s DOM overlays, developers can amend localized strings with additional non-localizable … Read more<\/a><\/p>\n","protected":false},"author":104,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[503],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts\/426"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/users\/104"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/comments?post=426"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts\/426\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/media?parent=426"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/categories?post=426"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/tags?post=426"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Using the XPath<\/a> syntax, the localizer identifies which source a<\/code> element to copy attributes from. The first <a><\/code> element in the translation<\/em> will be matched against the second <a><\/code> element in the source<\/em>. The meaning of a[2]<\/code> in XPath is:<\/p>\n