Shorten <fix> translation string variable syntax in CMS

[juliandoucette]

Background

We surround all brand names and numbers within translated strings in our CMS with <fix> tags so that they appear as variables within crowdin.

Although this is effective, it is inconvenient because:

• It requires HTML syntax inside of Markdown
• It is awkward to type repetitively

What to change

Support an alternative <fix> format.

Suggestions

=fixed=
-fixed-
{fixed}

[trev]

Convert all markdown pre tags (created by surrounding text with a single backtick) into translation string variables.

I just verified that Markdown module for Python produces <code> tags for backticks. Anything else would be very surprising as <pre> is a block-level tag and should never be placed within a paragraph.

Now I'm not sure what your first suggestion is about. Should we wrap brand names in <code> tags? Or should the CMS strip <code> tags? If the latter, what should we use when talking about filters or URLs on ​https://adblockplus.org/en/filters?

insert some combination of one or two non-shift characters

What for example? My keyboard doesn't have too many non-shift characters other than letters, it's only <,.-#+. I can only imagine using # here, and that one requires pressing Shift on US keyboards. Note also how Markdown already claimed all usable non-shift characters on US keyboards.

[juliandoucette]

I just verified that Markdown module for Python produces <code> tags for backticks. Anything else would be very surprising as <pre> is a block-level tag and should never be placed within a paragraph.

Verified. I was wrong about this :/ .

Now I'm not sure what your first suggestion is about. Should we wrap brand names in <code> tags? Or should the CMS strip <code> tags? If the latter, what should we use when talking about filters or URLs on ​​https://adblockplus.org/en/filters?

No. I was suggesting we override Markdown's conversion of backticks to pre tags. This was an invalid suggestion.

What for example? My keyboard doesn't have too many non-shift characters other than letters, it's only <,.-#+. I can only imagine using # here, and that one requires pressing Shift on US keyboards. Note also how Markdown already claimed all usable non-shift characters on US keyboards.

Good question.

A few suggestions:

non-shift

[fixed]
=fixed=
-fixed-

shift

{fixed}

[trev]

=fixed=

If I were to choose, I would probably go with this one even though it is non-shift on German keyboards - the equals sign makes this somewhat easier to remember.

[kvas]

Do I get it right that everybody would be happy with the =fixed string= format? From my side it looks fine. Perhaps we could write it into the test of the issue.

Can we also specify the list of characters that can be present inside of the fixed string? This would be needed to robustly replace them inside of markdown and HTML. I suppose it's alphanumeric characters, spaces, dashes, underscores, ., ,, ?, !, maybe parentheses... What else?

[fhd]

My thoughts:

[fixed] - I don't think we should use square brackets, Markdown already uses those for links.
=fixed= - Like Wladimir said, this makes some degree of sense since the string will stay the same (i.e. equal) in all languages.
-fixed- - This is used for strikethrough in Textile, so I personally find that confusing. YMMV.
{fixed} - We use {{ for our translation syntax and Jinja uses {%, so this could be confusing for some people. On the other hand, Java's MessageFormat uses { for parameters, and since I did my fair share of Java, to me it would actually be somewhat obvious and not confusing at all.

Long story short: It's = or { for me.

[trev]

Replying to kvas:

Can we also specify the list of characters that can be present inside of the fixed string? This would be needed to robustly replace them inside of markdown and HTML. I suppose it's alphanumeric characters, spaces, dashes, underscores, ., ,, ?, !, maybe parentheses... What else?

Why do we want to limit ourselves? Isn't it sufficient that the starting = is preceded by a space character and followed by a non-space, and for the ending = it's the other way around? This should be consistent with treatment of inline formatting in Markdown. Note that fixed strings can contain HTML tags.

[juliandoucette]

I agree with fhd, except:

• I wonder if escaping = inside of =fixed= would be annoying/confusing
• I like {fixed} even though it's a shift character because crowdin formats variables similarly

[kvas]

Replying to trev:

Why do we want to limit ourselves? Isn't it sufficient that the starting = is preceded by a space character and followed by a non-space, and for the ending = it's the other way around? This should be consistent with treatment of inline formatting in Markdown. Note that fixed strings can contain HTML tags.

Yes, seems like it would work. And in case we have an = sign with space on on side and no space on the other that is not a fixed string marker, we can always escape it using HTML entities (&equals; or &#61;).

BTW, if a fixed string contains HTML tags, do opening and closing tags inside of it have to be balanced?

Replying to juliandoucette:

I wonder if escaping = inside of =fixed= would be annoying/confusing

We would only need to escape = that has a space on one side and no space on the other side. This seems to be rather uncommon in normal text. And things like foo = bar or foo=bar would just go through unchanged.

I like {fixed} even though it's a shift character because crowdin formats variables similarly

I find it somewhat confusing, since it's similar to many other constructions (ours and Jinja's) but if it seems convenient to you, perhaps that's more important, since you're using the CMS much more.

[trev]

BTW, if a fixed string contains HTML tags, do opening and closing tags inside of it have to be balanced?

It has to be valid HTML code by itself - we will feed it to an HTML parser. But we don't really enforce anything there, nor do I see why we should.

[juliandoucette]

I find it somewhat confusing, since it's similar to many other constructions (ours and Jinja's) but if it seems convenient to you, perhaps that's more important, since you're using the CMS much more.

We should confirm with @saroyanm and @lisabielik.

[lisabielik]

Replying to juliandoucette:

I find it somewhat confusing, since it's similar to many other constructions (ours and Jinja's) but if it seems convenient to you, perhaps that's more important, since you're using the CMS much more.

We should confirm with @saroyanm and @lisabielik.

I don't have a preference. Whatever works for the majority is fine with me.

[juliandoucette]

I think #5340 makes this irrelevant.

[kvas]

Replying to juliandoucette:

I think #5340 makes this irrelevant.

Yes, you're probably right. Shall we close it then, or wait until #5340 is implemented?

[juliandoucette]

Yep.