Skip to content

Editorial: I18n considerations for translatable attributes #2862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
daniel-montalvo wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Editorial: I18n considerations for translatable attributes #2862

Changes from 3 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
eed86f6
Second pass at i18n prose
daniel-montalvo Jul 29, 2026
ea09984
update prose
daniel-montalvo Aug 4, 2026
aa85a8e
Add containing element
daniel-montalvo Aug 4, 2026
ca99c58
Add period
daniel-montalvo Aug 6, 2026
a9386c9
Update index.html
daniel-montalvo Aug 12, 2026
6dd499c
Update index.html
daniel-montalvo Aug 12, 2026
5887844
Update index.html
daniel-montalvo Aug 12, 2026
f88229c
Remove first sentence (not needed)
daniel-montalvo Aug 12, 2026
13dae5f
"plain string" -> "plain text"
daniel-montalvo Aug 12, 2026
60d0074
Acknowledge that most of the times these elements content is not rend…
daniel-montalvo Aug 12, 2026
2b2bbb1
Merge branch 'main' into i18n-prose-for-translatable-attributes
daniel-montalvo Aug 12, 2026
637c13b
Merge branch 'main' into i18n-prose-for-translatable-attributes
daniel-montalvo Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12060,6 +12060,18 @@ <h2>Translatable Attributes</h2>
<li><pref>aria-rowindextext</pref></li>
<li><pref>aria-valuetext</pref></li>
</ul>
<p>
The web accessibility stack does not currently provide a mechanism to specify language and directionality for a translatable attribute other than the language and directionality of its containing element. This includes <pref>aria-labelledby</pref> and <pref>aria-describedby</pref> because the <a href="" class="accname">Accessible Name and Description Computation</a> [[ACCNAME-1.2]] results in a flat string.
Comment thread
daniel-montalvo marked this conversation as resolved.
Outdated
</p>
<p>
Translatable attribute values that don't match the language and directionality of their containing element can also cause other accessibility problems. It is best practice for authors to ensure that the language and directionality of the value of a translatable attribute matches the language and directionality of its containing element.

@cookiecrook cookiecrook Aug 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you call out "other problems," it would be wise to list a known example.

Alternately, cut the first sentence for brevity, because the second stands on its own.

@daniel-montalvo daniel-montalvo Aug 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd just cut off the first sentence as you suggest. Listing individual problems here may end up making this a maintenance burden if the guidance changes in the future.

@pkra pkra Aug 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is an important sentence to keep. I gave an example in https://github.com/w3c/aria/pull/2849/changes#r3614624182, almost straight from a WCAG failure document.

@pkra pkra Aug 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be very intrigued to see an intentionally authored example where aria-label is in a different language from the element's content without being problematic.

@pkra pkra Aug 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Someone kindly pointed me to https://html.spec.whatwg.org/multipage/dom.html#the-lang-and-xml:lang-attributes:

The lang attribute [...] specifies the primary language for the element's contents and for any of the element's attributes that contain text.

Generally speaking, having different (primary) languages in accname and visible content seems to invariably fail WCAG 2.5.3.

</p>
<p>
Where language or direction metadata for the translatable attribute value needs to differ from that of its containing element, it is recommended that authors use a referencing attribute, such as aria-labelledby, aria-describedby, or aria-details, pointing to host-language content on which language and direction can be expressed directly. This would allow translation of these values when the user agent is presenting the document in a machine-translated rendering (for example, via a built-in "Translate this page" feature). Authors are encouraged not to use plain string ARIA attributes for text alternatives that contain inline language/direction changes or other text-level markup.
Comment thread
daniel-montalvo marked this conversation as resolved.
Outdated
</p>
<p>
For more details, see <a class="informativ" href="https://www.w3.org/TR/international-specs#markup_elements_attributes">Internationalization best practices for web developers</a>
</p>
</section>
<section id="global_states">
<h2><dfn>Global</dfn> States and Properties</h2>
Expand Down
Loading