Mark strings for screen readers

[pavelevap]

Sometimes there are "hidden" strings which are for screen readers, but translators have to search for context to find the real meaning. Maybe we could mark all these strings somehow (comment for translators or context) to make it easier?

I can create patch if you think that it is a good idea (and we can also discuss best solution before: comment or context).

[SergeyBiryukov]

A translator comment sounds like a good idea.

[ocean90]

A translator comment might be helpful, yes.

@swissspidy proposed that this should be added to the handbook (​https://make.wordpress.org/core/handbook/best-practices/internationalization/) and considered for future strings. I tend to agree with that. Any suggestions for a comment?

[Chouby]

A translator comment looks more adapted than context for me. May be useful to add this to ​https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/ to extend the practice to plugins (the same for themes).

[swissspidy]

Replying to ocean90:

A translator comment might be helpful, yes.

@swissspidy proposed that this should be added to the handbook (​https://make.wordpress.org/core/handbook/best-practices/internationalization/) and considered for future strings. I tend to agree with that. Any suggestions for a comment?

What about simply using screen reader text or maybe only visible to screen readers? assistive text for screen readers?

[ocean90]

Replying to swissspidy:

What about simply using screen reader text or maybe only visible to screen readers? assistive text for screen readers?

We already have a few "accessibility text" comments for aria-label placeholders.

[SergeyBiryukov]

Related BuddyPress ticket: ​#BuddyPress6951

[mercime]

First batch of translator comments for accessibility text

[mercime]

Second batch of translator comments for accessibility text

[mercime]

wp-admin - refreshed translator comments

[mercime]

wp-includes - refreshed translator comments

[mercime]

wp-content - refreshed translator comments

[mercime]

Refreshed patches are attached and re-organized as follows for your review:

• 29748-wp-admin.patch
• 29748-wp-includes.patch
• 29748-wp-content.patch

[jipmoors]

Just adding "accessibility text" doesn't really complete clarifying the context for the strings. Especially for "Page" which I saw as a pagination use.

[afercia]

Replying to jipmoors:

Just adding "accessibility text" doesn't really complete clarifying the context for the strings. Especially for "Page" which I saw as a pagination use.

Yep maybe the text could be improved a bit. What translators really need to know? I'd say:

1. it's hidden text, not visible in the UI so better they don't waste time trying to find the place where this text is displayed because... well, it is not displayed at all
2. it is used to expand short labels and sentences to give more context or add feedback where otherwise the feedback is only visual

Anyone able to summarise all this in a very short sentence? :)

[afercia]

Strings used to expand UI controls text and strings used for wp.a11y.speak() messages are a bit different in their scope, but I'd rather keep things simple and use something like hidden accessibility text. Any thoughts welcome!

[SergeyBiryukov]

Replying to afercia:

I'd rather keep things simple and use something like hidden accessibility text.

Seems good to me.

[desrosj]

Found this one going through tickets without milestones.

It seems like hidden accessibility text was the preferred description that was landed on, but this was ​never added to the i18n handbook.

There are currently 21 occurrences of translators: accessibility text in trunk, all in JS files. These instances are also a bit more verbose, such as accessibility text for the widgets screen top bar landmark region and accessibility text for the footer landmark region.

The patches attached here also need to be refreshed. A ​GitHub pull request would probably be best to manage these.

Trac ticket:

[kebbet]

Added a WIP-pr to the ticket.

[kebbet]

In linked PR: All screen reader strings in wp-admin have an added comment on its visibility. The ones which has a placeholder are constructed like this:
/* translators: hidden accessibility text. %s: Theme name */

[kebbet]

Linked PR at GitHub is ready for review, only 132 files touched. And only PHP-files.

I kept some existing translation comments like
/* translators: Only visible to screen readers */

And I went with this comment everywhere else:
/* translators: hidden accessibility text */

Thanks for the PR!

Pretty much all of the comments in core are capitalized and end with a period, so let's do the same here:

/* translators: Hidden accessibility text. */

There are also these comments previously used for the same purpose (32 matches in 16 files)

/* translators: Accessibility text. */

Let's change them to use new wording too, for consistency.

Thanks for the PR!

Pretty much all of the comments in core are capitalized and end with a period, so let's do the same here:

/* translators: Hidden accessibility text. */

There are also these comments previously used for the same purpose (32 matches in 16 files)

/* translators: Accessibility text. */

Let's change them to use new wording too, for consistency.

Thank you for the review. I will adjust the PR later tonight.

@SergeyBiryukov pr updated in response to your comment. Maybe ready for final review and commit?

[costdev]

I've reviewed ​PR 3970 and aside from a tiny mistake in one instance that can be updated during commit ​See here, the rest looks ready for commit consideration.

[kebbet]

The mistake has been fixed, thanks for reviewing @costdev !

[costdev]

Thanks @kebbet! The PR looks good to me! 🙂

[kebbet]

The ticket owner has not been active for years, could someone else take ownership and get this commited before 6.2 beta1?

@costdev @audrasjb @SergeyBiryukov

[audrasjb]

I checked the changeset and it looks good to ship with 6.2 on my side!
Let's commit this before beta 1.

[audrasjb]

Oh just noticed that Sergey took ownership. Perfect! 🙏

[SergeyBiryukov]

In 55276:

I18N: Mark screen reader strings as such with translator comments.

This aims to provide better context for translators and make it easier to determine that some strings contain hidden accessibility text and are not displayed in the UI.

Props kebbet, mercime, pavelevap, ocean90, swissspidy, Chouby, jipmoors, afercia, desrosj, costdev, audrasjb, SergeyBiryukov.
Fixes #29748.

Thanks for the PR!

I have found a few misaligned closing tags and tried to correct them on commit, also made some minor formatting edits for consistency. Looks great to me otherwise 🙂

Merged in r55276.

[swissspidy]

This will be added to the dedicated i18n dev note

[SergeyBiryukov]

In 55422:

Twenty Seventeen: Mark one more screen reader string with a translator comment.

Includes minor comment layout fixes for consistency with other themes.

Follow-up to [55276].

See #29748.

[milana_cap]

Dev note ​https://make.wordpress.org/core/2023/03/03/i18n-improvements-in-6-2/