[UX] Improve form item label text for new SVG icon views field handler

[jenlampton]

Description of the bug

We need to decide on improved text for labels in https://github.com/backdrop/backdrop-issues/issues/6588

Current text:

Curent recommendations:

Embedded file with <svg> tag. Embedded SVG images are usually more efficient and easier to style.

Referenced file with <img> tag. Referenced SVG images can be more efficient when showing the same icon many times.

Display text alternative For icons that are decorative only, alternative text should be omitted. A text alternative is used to describe the icon for assistive tools like screen readers.

Other Recent recommendations:

Inline <svg> tag Inline SVG images are usually more efficient and easier to style.

Regular <img> tag Regular image tags can be more efficient when showing the same icon many times.

Add alternative text If alternative text is omitted, this icon will be marked as decorative only.

[indigoxela]

A screenshot of what we have now:

With the descriptions added to display type, there's now text duplication, that doesn't seem to add value.

Another thing re suggestions: strings like

Inline <svg> tag
Regular <img> tag

are too similar next to each other to easily distinguish, and produce awkward translation strings like:

Inline <code>&lt;svg&gt;</code> tag

Note that a translator has to identify the "svg" inside that stuff they may not touch to not break the whole string, as the relevant difference would be these hard to spot three chars.

For the alternative text we discussed something like:

• Title: Text alternative
• Desc: Add a text alternative to describe the icon for assistive tools like screen readers.

To use "text alternative" can make sense, as for SVG tags that's a <title> tag, for IMG tag it's the alt attribute. Their purpose is the same.

[avpaderno]

I would rather use a checkbox form element, instead of a radios form element, since that setting is asking if SVG images should be used. That would avoid to call the usual JPEG, PNG, and GIF images regular images.

[indigoxela]

... since that setting is asking if SVG images should be used

Changing the form item type to circumvent a wording discussion? Am I getting this right? Hm... that seems a bit odd to me. :wink:

It's radios, because people can pick between two different rendering options, a checkbox would obfuscate that IMO. And I'd find it confusing.

@avpaderno Besides that, it's also off topic here, as the issue's supposed to cover form wording only. If you're convinced, the form item decision was wrong for whatever reason, it might be clearer to just open a new issue for that.

[avpaderno]

Those two options are SVG or not SVG.

Anyway, my comment was just meant to say that it is difficult to say Use images that are not SVG images without saying Use images that are not SVG images. Regular images does not say anything about which images would be used, especially because regular can also mean used, done, or happening on a habitual basis; usual. For somebody who uses SVG images all the times, those are the regular images.

[wesruv]

"Regular Image" doesn't work for me either, we talked about it in the Backdrop UX meeting, this is my thought that I think addresses the lack of clarity for me.

Referenced Image Use an <img> tag that points to the SVG, which can be faster if the image shows up many times on the page, but isn't easy to recolor and is less stylable.

[jenlampton]

Another thing re suggestions: strings like [....] are too similar next to each other to easily distinguish

I think including the tags that will be used is critical, since that's what we're asking to choose between. Without using example tags I don't understand why a SVG tag isn't "regular".

and produce awkward translation strings

@quicksketch recommended that the tags should not be included in the translation, since the HTML tag itself is not different across languages.

t('Embedded file with !tag tag', array('!tag' => '<code>&lt;svg&gt;</code>'));
t('Referenced file with !tag tag', array('!tag' => '<code>&lt;img&gt;</code>'));

Those two options are SVG or not SVG.

Those aren't the two options though. We're going to use a .svg file either way. If someone selected "not svg" they might be expecting to see a .gif or something else.

The question is how we render that SVG file, using an <img> tag, or a <svg> file.

<svg></svg>
<img src="icon.svg">

Because the main difference between these two methods is whether the file is embedded or referenced, I'd like to recommend that we use those two words in addition to the actual tag as an example.

Embedded file with <svg> tag. Referenced file with <img> tag.

[jenlampton]

For the alternative text we discussed something like:

Title: Text alternative Desc: Add a text alternative to describe the icon for assistive tools like screen readers.

To use "text alternative" can make sense, as for SVG tags that's a

I love Text alternative here, but we should indicate that this is a display setting, and not a place where the text can be added. How about Display text alternative

I'm not thrilled with Add a text alternative to describe the icon for assistive tools like screen readers. because it reads like an imperative "Do this!". In most cases, we don't actually want people to do it because these icons will be decorative.

What if we combined both, something like:

For icons that are decorative only, alternative text should be omitted. A text alternative is used to describe the icon for assistive tools like screen readers.

[olafgrabienski]

For icons that are decorative only, alternative text should be omitted. A text alternative is used to describe the icon for assistive tools like screen readers.

I'd suggest to turn the sentences around: First explain what 'text alternative' is, then add the restrictive phrase.

A text alternative is used to describe the icon for assistive tools like screen readers. It should be omitted for icons that are decorative only.

However, I find the phrase "is used" in the first sentence ambiguous. In a way, it both explains the general concept of text alternatives, and it gives an indication what Backdrop does when you enable the option. Reading the sentence, I wouldn't know what to expect: Does Backdrop add a certain text, or do I (have to) add my custom text?

Hopefully slightly clearer suggestion:

Adds a text alternative which describes the icon for assistive tools like screen readers. Do not enable for icons that are decorative only.

[indigoxela]

Let's start iterations, here's the next version:

[olafgrabienski]

I like the text changes, nice! I also tried to check the translation strings in the sandbox of the PR, but so far they didn't appear in the translation interface, even though I created a file icon view.

[indigoxela]

I also tried to check the translation strings in the sandbox of the PR, but so far they didn't appear in the translation interface

Odd, I can find them. My usual trick: switch to the other language (DE in that case) once. Then the new t() stuff usually shows up on /admin/config/regional/translate/translate.

[indigoxela]

BTW, personally, I'd suggest to remove the wrapping <code> tags - to me they seem distracting (the code highlighting depends on the admin theme, but there will be some highlighting in all of them, I guess).

And the translation string looks confusing: Referencing via <code>&lt;img&gt;</code> .... But that's maybe just me. :wink:

[olafgrabienski]

My usual trick: switch to the other language (DE in that case) once

Oh yes, forgot that, thanks a lot, works like a charm!

I'd suggest to remove the wrapping <code> tags ...

I agree, without <code> tags does the job, but even then the string in the translation interface looks ugly: Referencing via <img> ... (I vaguely recall a suggestion by @quicksketch to not translate the file extension itself, but can't find it at the moment.)

[avpaderno]

With t('Embedded file with !tag tag', array('!tag' => '<code>&lt;svg&gt;</code>')), what the translators see is Embedded file with !tag tag; the user interface will not show <code>&lt;svg&gt;</code> to translators.

[indigoxela]

@avpaderno I like your suggestion. :+1: I'm not sure, if that's "allowed", though. The rules around t() can sometimes be a bit confusing. Can anyone confirm, that it's OK to wrap the tag code like that?

Bear with me, I hate to put some pressure here, but we're slowly running out of time for the stable release. :grimacing:

[laryn]

@indigoxela Yes, I believe that's allowed. It was also suggested earlier, so I think we have pretty good consensus that it is a reasonable approach:

https://github.com/backdrop/backdrop-issues/issues/6701#issuecomment-2332632593

[avpaderno]

The suggestion was from jenlampton/quicksketch. I just commented saying that string does not ask translators to translate <svg>.

[indigoxela]

The suggestion was from jenlampton/quicksketch...

Wow, how did I miss that comment. :grimacing:

Anyway, next version looks like this:

[olafgrabienski]

Tested in the sandbox, works for me, including translating the strings (see below). Great!

For the record, these are the new translator friendly strings:

• Embedded with !svg tag
• Referenced with !img tag

[jenlampton]

I did a code review, and the code change looks good!

I do have a few thoughts on the text:

1. My preference is to match the syntax in the descriptions for the two options, so they both start with ADJECTIVE(S), NOUN, VERB, rather than the second stating with a gerund:

• Inline SVG icons are ....
• Referenced images can be ...

2. I'm not a fan of With text alternative as a label. It's only a phrase and could translate oddly. I would prefer if this were a complete sentence like Add text alternative or Include text alternative.

3. Adds a descriptive text is not grammatically correct in English, I think we should make this Adds descriptive text. instead, omitting the a.

I love the new Do not enable for icons that are decorative only :)

[indigoxela]

@jenlampton wording updated accordingly. Many thanks for having a look. :+1:

[quicksketch]

Thank you everyone! I merged https://github.com/backdrop/backdrop/pull/4865 into 1.x for 1.29.0.

https://github.com/backdrop/backdrop/commit/4df763da1894e40abdcf059c351a2f3b69c4d36f by @indigoxela, @jenlampton, @quicksketch, @avpaderno, @olafgrabienski, @laryn, and @wesruv.