Allow reordering child elements in translations in DOM overlays about fluent.js HOT 13 CLOSED

I think we're trying to achieve two things with DOM overlays:

• localizers can use richer markup to do italic as quotes, or the like
• programmers of DOM-like targets can pass DOM-like nodes as parameters to localization, so allow to mix up localizable and non-localizable attributes.

The current code is pretty good at the first, but doesn't serve us well on the latter (parameters).

I think this is a good summary of the goals, thanks. I checked back to the DOM Overlays spec from L20n and it's pretty close to the goals defined there:

• Make it possible to localize content in HTML elements and attributes without forcing developers to split strings into pre- and post- parts (definitely a bad practice). For instance, it should be possible for an element to be a part of the translation.
• Make it possible for localizers to apply text-level semantics to the translations and make use of HTML entities. For instance, it should be possible for a localizer to use a sup element in "Mme" (an abbreviation of French "Madame") even if the original source string doesn't contain the sup element.

I think the crucial part which you pointed at but the L20n's goals didn't, is that some elements are in fact arguments to localization. It makes sense to me to name them then.

This is also closer to what fluent-react already does in its implementation of overlays. It will be great to see the concepts behind the implementations in fluent-dom and fluent-react converge.

I'd like these two above overlay behaviors to be explicit and separate:

• If an element in the translation doesn't have the data-l10n-name attribute (attribute name TBD), then treat it as a text-level semantics element: always allow it but sanitize unsafe attributes.

• If an element does have the data-l10n-name attribute, try to find an element of the same type and the same data-l10n-name in the source. If it exists, sanitize the translation and overlay it onto the source child (perhaps keep referential identity; see note below). If a corresponding source child is not found, just use the textContent from the translation. The source element could also have data-l10n-attrs defined to allow more than the default safe set of attributes.

Note: This design relates to #144. A translation might remove a child element from the source. Any further re-translations will not be able to find the removed element anymore. We should see if we can fix this. If not, we should consider not keeping the referential identity of the overlaid elements to make it explicit that developer cannot rely on them for the app logic.

from fluent.js.

I don't understand this objection. Developers write ids and classes for theme authors to easily reach elements in their language. Seems like the same should work well for localization.

I meant this in the same way we don't want developers to think about whether a particular message in the UI requires plurals in other languages than the source language.

However, if we consider those elements as arguments to the translation and explicitly treat them like that (and not conflate them with the allowed text-level elements), I think it's a good idea to name them. Just like we name all other arguments.

from fluent.js.

@stasm I like it! @Pike - does it sound reasonable to you?

from fluent.js.

My expectation is that that's going to be hard to add. Also, we don't do anonymous unique arguments elsewhere in fluent, so I'm not too concerned about that. That said, as in other cases with named arguments, giving the a name adds context for the intent of that image, which can be helpful in localization to some of the weirder languages that have problems with yes/no and such.

from fluent.js.

TBH, instead of creating side-effects of the feature, we should focus on what we're really doing:

We sanitize HTML safely, and take a lot of l10n content markup away from developer's shoulders.

I expect them to jump up and down in joy over just having to add an attribute to get their non-localizable elements and attributes into the target DOM.

from fluent.js.

The first design principle of Fluent is Control and Isolation. In particular I'd like to highlight two statements:

• The localizers should have control over the translation.
• The localization logic of one language doesn't leak into other other languages nor into the source code.

I think #143 is a good first attempt of the issue. It satisfies the first statement but it breaks the second one. The developers should not have to put anything in the source code for localizers to be able to reorder elements. Instead they should write their source code in an as agnostic manner as possible. Localizers interested in reordering should be able to do so via some additional syntax or markup.

For this reason, I don't think we should give child elements names but instead, allow localizers to use CSS's structural pseudo-classes to match desired elements.

I'd go for something like the following to make it easy to recognize the CSS:

Source:

<a href="foo">foo</a> <a href="bar">bar</a>

Localization:

<a data-l10n-select=":last-child">bar</a> <a data-l10n-select=":first-child">foo</a>
<a data-l10n-select=":nth-child(2)">bar</a> <a data-l10n-select=":nth-child(1)">foo</a>
<a data-l10n-select=":last-of-type">bar</a> <a data-l10n-select=":nth-of-type(1)">foo</a>

In code, we could use something like:

let localName = sourceChildElement.localName;
let selector = translationChildElement.getAttribute('data-l10n-select');
sourceElement.querySelector(`${localName}${selector}`);

data-l10n-select or data-l10n-match would be my picks for the attribute name.

from fluent.js.

I have a different take on this.

I think we're trying to achieve two things with DOM overlays:

• localizers can use richer markup to do italic as quotes, or the like
• programmers of DOM-like targets can pass DOM-like nodes as parameters to localization, so allow to mix up localizable and non-localizable attributes.

The current code is pretty good at the first, but doesn't serve us well on the latter (parameters).

One thing that I went for early on is that we shouldn't have positional parameters, but only named parameters. That was done recognizing that in some languages named parameters weren't a thing, and that we'd need programmers to create sometimes non-canonical boilerplate to work around that. data-l10n-args being serialized JSON is one of those.

Sadly, I don't find that verbatim in the principles, but it surely should be one, I think.

In the case of DOM nodes, we have somewhat-named parameters right now, by having node names. This doesn't seem to serve us well. I'd rather see us going for full-name.

In closing, I think that parameter reordering is common enough among languages that it should fall into the simple bucket, instead of the possible bucket.

from fluent.js.

The developers should not have to put anything in the source code for localizers to be able to reorder elements.

I don't understand this objection. Developers write ids and classes for theme authors to easily reach elements in their language. Seems like the same should work well for localization.

For this reason, I don't think we should give child elements names but instead, allow localizers to use CSS's structural pseudo-classes to match desired elements.

I find the CSS pseudo-classes much harder to work with than names, and they also refer to, as Pike pointed out, order, rather than names.
This, imho, will in the future make any smart Pontoon UI for this less useful as it'll have to provide a GUI for assigning elements to the order of elements in the source, rather than to the names (addons-icon, toolbar-icon).

from fluent.js.

One note - possibly for later. I think it's a bit daunting to have to write data-l10n-name for cases where there is only one element:

<p data-l10n-id="key1">
  <img src="http:/www.mozilla.org/logo.png" />
</p>

key1 = Click on <img/> to open Preferences

It would be nice to have a way in the future to make Fluent "guess" which <img/> I mean here.

As I said, I can see it as v2 addition, but I think it would be nice to agree on that and make sure we have a way to add a feature like this in the future. wdyt?

from fluent.js.

I agree with @Pike.

from fluent.js.

Could we use the name as alt text in the image case? You know, to make it double duty as a11y enhancement? (And if alt name is set, don't override it to allow for exceptions)

from fluent.js.

I'm not sure I see the value of of such special-casing. What are you trying to achieve? :)

from fluent.js.

I'm trying to capture the value of the named attribute as some sort of fallback. We use most of our ids (be it message id, or external argument id) as a last resort meaningful feedback for the user. If we can't resolve $tabCount at least there's a chance the user will be able to deduct the meaning from the name (compared to, say 0), same with enable-extensions-label.

My current concern is that asking developers to add data-l10n-name in a single-element case, with a reason of "we have to know which element to match" is not going to hold, because in a single element case we can deduct it easily. We can still enforce it for conformity "we need it for when there are two elements of the same type, so you should put it even if there's one" but that one will be likely countered with "the common case is with a single element, how about we simplify it".

If we can find an additional use for the data-l10n-name - for example as an alt-text, which could serve as a text to be displayed if the image is not loaded, then we justify adding them to each element.

I'm just trying to wear a user hat. From the user standpoint, I expect devs to want us to make the example I gave above with key1 to just work, without the need to assign a name.

from fluent.js.