Remove translator comments when hidden text matches visible text

[sabernhardt]

#29748 added translator comments for hidden accessibility text. However, text in a hidden fieldset legend often matches the visible text immediately before it (in a th cell or a heading).

I think the 'Hidden accessibility text' comment should be removed from:

• all of the hidden legends in options-discussion.php, options-general.php, options-media.php, options-permalink.php, options-reading.php, and options-writing.php
• the legend for site or search engine visibility in install.php
• all five hidden legends in includes/class-custom-background.php
• most—but not all—hidden legends in includes/meta-boxes.php ('Target' and the XFN option groups for the old Links Manager)
• 'Administration Color Scheme' in includes/misc.php because it has the same text visible in user-edit.php
• 'Enable menus' in network/settings.php, if it changes to match the visible 'Enable administration menus' text
• none of the legends in edit-form-comment.php, export.php or network/site-info.php

The 'Hidden accessibility text' comment seems inappropriate when a visually hidden legend (<legend class="screen-reader-text">) has the same text as visible text next to it.

This removes the comment from several fieldset legends:

• all of the hidden legends in Settings pages (options-discussion.php, options-general.php, options-media.php, options-permalink.php, options-reading.php, and options-writing.php)
• 'Site visibility' or 'Search engine visibility' on the installation page (install.php)
• option groups in the Custom_Background class (includes/class-custom-background.php)
• 'Target' and XFN option groups for the old ​Links Manager meta boxes (includes/meta-boxes.php)
• 'Administration Color Scheme' in profile pages (includes/misc.php)
• 'Enable administration menus' in network/settings.php, matching the hidden legend to the _visible_ text

Trac 63620

[swissspidy]

I am -1 on removing valuable information for translators.

It's true that the current situation is not ideal because there are identical strings, so in the end it's 1 string in GlotPress with a sharedtranslator comment, which is confusing.

However, the better solution here is to add context to the string to distinguish them. So we should add more information for translators, not remove information.

[audrasjb]

@sabernhardt is duplicated strings the only issue you want to solve here? If it is the only issue, I think it's fine to keep the context as there is only 11 strings involved.

[sabernhardt]

in the end it's 1 string in GlotPress with a shared translator comment, which is confusing.

For example, '​Email me whenever' is used exactly twice in the administration, both to describe the same fieldset. Translators can read the comment for the hidden string even though the same text is also visible. If the comment changes how someone translates the text, that translation might not be appropriate for the header cell.

the better solution here is to add context to the string to distinguish them.

I counted 36 strings in the (current) PR, and I do not wish to create so many new strings with the _x() context. An even better solution would be displaying the legend without repeating the same text in a table header cell. The upcoming admin redesign might revise the layout for settings pages, and maybe concentrating on that is a better way forward than making edits on this ticket.

is duplicated strings the only issue you want to solve here?

Not the only reason. I started looking at this because the 'Enable menus' legend did not match the 'Enable administration menus' visible text. The header cell text is more precise, and screen reader users who can see the page could benefit from an exact match. Of course, adding the word 'administration' in that legend should also reduce the total strings by one.

---

History:

• #6859 added the hidden legends
• [11180] changed the class name from .hidden to .invisible
• #9783 added span elements
• #9791 changed the class name to .screen-reader-text

[joedolson]

Could we instead just assign these strings to a variable, then *actually* only have one string? If the two strings are the same, I think we're just complicating things by having two separate translatable strings in the first place. If the first thing that @sabernhardt noticed was a mismatched pair of strings, that's a preventable problem by not having two strings.

[swissspidy]

We're not complicating anything, there are no duplicate strings in the translation tool because of this.

[sabernhardt]

reuses 'Enable administration menus' as the legend text, to match the visible header cell

[sabernhardt]

The strings are not exactly 'separate' or 'duplicate'. The same string is in at least two places, but one identifies its context without acknowledging the other context(s).

I don't think we will agree on a change like PR 9080, and I did not fully expect agreement when I opened the ticket (especially considering that #29748 involved at least seven committers).

Except for the new 'Administration Color Scheme' string (updated in r60284), most of these strings already have more than 100 approved translations. Therefore, the comment could have a very low probability of leading to a less accurate translation in the future.

For a small edit, the 'Enable menus' legend could match the 'Enable administration menus' visible text.

Two other header cells do not match their corresponding legend, but at least one legend seems appropriate enough the way it is:

• 'Allow new registrations' header with 'New registrations settings' as hidden legend (​network/settings.php)
• 'Attributes' header with 'Set site attributes' as hidden legend (​network/site-info.php)

[joedolson]

@swissspidy I'm not referring to complicating translations; I mean complicating the codebase and maintenance of duplicate strings.

The purpose of the screen reader hidden text in a legend is to provide grouping context for grouped controls. This text should match the visual text. This is all a hack for the fact that the Settings API is inadequate for accessibility.

Screen reader users should get the same group name that sighted users get, so in every case where it doesn't match, I would consider that an error.

There is no reason to know it's screen reader text if it's always going to match the visible text, and if these were assigned to a variable then we'd be more sure that future edits to the text are consistent between both uses.

Using a variable, wherever possible, the visually hidden legend text matches the visible text that describes the same fieldset.

Strings that do not use a variable but still remove the "Hidden accessibility text" comment:

• 'Target' in the Links metabox, because it matches the ​metabox heading in `edit-link-form.php`
• 'Administration Color Scheme' in the profile screens, because the ​table header is in `user-edit.php`

Trac 63620

[sabernhardt]

I started PR 9396 for the variables, which probably would need more editing if that is preferred.

Both pull requests now have 'Allow new registrations' and 'Attributes' as the legend text, to match the visible text.

[joedolson]

I think this would be a good change; I don't think there's a value to having these duplicated strings be separate literals in the code.

@swissspidy do you have an opinion on this? At this point, this is more about keeping the code DRYer and removing risk of mismatch between screen reader text and visible text when those two should be duplicates. It won't have any impact on translators, I think.

[swissspidy]

One impact is that translator comments are removed, but I suppose in this instance it's ok.

[joedolson]

That's my feeling. These translator comments don't actually advance anything, since the text *is* visible, as well.

Milestoning for 6.9.

[joedolson]

I don't think any testing beyond @sabernhardt's and mine is required here. I checked to verify that any _e() was now an __() and that the variables were actually echoed, but effectively has no actual changes in output.

Marking for commit.

[joedolson]

One important decision here is that I chose to remove the hidden text comment on strings that were not switched to variables. This is because GlotPress shows strings where *any* instance of that string is hidden accessibility text as having that translator comment. But if there is a visible instance of the string, then that's what should be prioritized.

[joedolson]

In 60805:

I18n: Combine duplicate text strings into variables.

In cases where a string is used both for a visible label and a screen reader text label, the screen reader text should never be different from the visible label. To help ensure this doesn't happen, use only a single string. The associated screen reader text comments are no longer required.

This is also true for a few cases where there are strings in contexts where variables can't be used. In these cases, the screen reader text comments are also removed.

Props sabernhardt, swissspidy, audrasjb, joedolson.
Fixes #63620.

In r60805

Changes committed in r60805, using variables