Localization differences - Address EmbedLiveSample case with its "localized" argument

As far as I understand, EmbedLiveSample macro builds the sample content based on a given heading ID (first parameter) or (I just discovered this) fallbacks without argument by using an algorithm based on content.

The thing is, EmbedLiveSample is:

• considered as a macro of interest for “localization differences”
• still vastly using an argument based on the heading ID

As the localization differences take into account macros and their arguments, and as headings’ IDs are generated based on their content… We often encounter what I think are false positive signals when translating (see the first flaw on https://github.com/mdn/translated-content/pull/3158#issuecomment-974766571 for example). Before corresponding PRs it was actually one of the most important source of issues for French content on mdn/translated-content.

There are a few ways to fix this:

• Remove IDs in EmbedLiveSample macro calls in mdn/content and mdn/translated-content (as it mdn/content acts as the source of truth/reference for mdn/translated-content)
• Remove EmbedLiveSample from the list of “macros of interest” for localization differences
• Add some complexity in the localization difference detection algorithm to specifically deal with EmbedLiveSample (and any other macros with arguments based on localizable content)

I’m not sure of the way I prefer. EmbedLiveSample has long been frail regarding l10n (cf. https://github.com/mdn/translated-content/issues/2844 and https://github.com/mdn/translated-content/issues/2842 for example among others).

• Using no argument as the default would indeed solve the root cause of the issue but updating this in current content would need a large set of changes in mdn/content and mdn/translated-content.
• Removing EmbedLiveSample from the localization differences check is the most easy one but it feels wrong as, I believe, good live samples are essential to the quality of a page (whether it’s an English or a localized one)
• Making an exception for EmbedLiveSample in the current algorithm only has an impact on mdn/yari but feels a bit like a “ad hoc” solution.

Pointers:

• Peter’s comment on building localization differences https://github.com/mdn/yari/pull/3106#issuecomment-826886796
• Will’s comment https://github.com/mdn/content/issues/3548#issuecomment-854067354 which lead to https://github.com/mdn/yari/pull/3973
• Translation differences implementation lives in https://github.com/mdn/yari/blob/main/content/translation.js

@escattone @wbamberg @lex111 @mfuji09 @hochan222, let me know if you have any thoughts about this.

[wbamberg]

The situation is described above and hasn’t changed. To summarise:

• EmbedLiveSample is fragile for localizers, because it includes the ID, which is derived from the heading text, which is obviously locale sensitive
• there is an alternative behavior built into EmbedLiveSample in which the ID can be omitted
• when we tried using it we found a couple of issues: https://github.com/mdn/yari/issues/4971#issuecomment-981498547 . One of these seems not to be an issue any more, the other is but maybe we could work around it.

If we want to go ahead with the ID-less version (and that’s at least partly a choice for translators, but in this thread they seem pretty keen) then we should make sure it is working properly with our content and consistently use it in en-US and other locales. We should also consider revising the EmbedLiveSample API at the same time (https://github.com/mdn/yari/issues/5016).

[wbamberg]

Was talking this over with Ryan yesterday and it might be a good time to move to a new macro or to revise the arguments it can take. Already it takes 2 arguments that are always ignored (“width” and “hide Codepen buttons”).

Is there a tracking bug to discuss and do this work? Either creating a new macro or refactoring the existing one.

I just filed https://github.com/mdn/yari/issues/5016 for that.