Unified strategy for providing localized labels within components

[jattasNI]

🧹 Tech Debt

Labels for Icons

There are several places where components display icons. Each of these might benefit from:

1. setting title so that sighted users can hover over them to see the icon explained in a tooltip
2. setting aria-label or other attributes so that screen reader users can understand their purpose
   Those strings should be localized. Since we've decided that localization is an application concern and not a Nimble concern, we need to provide (hopefully consistent) APIs for clients to supply these strings.

We may also decide not to set title and to exclude the icon from the accessibility tree if its meaning is provided in other ways. We should consult with Leslie and with web best practice docs to come up with guidance for this.

The icons we've identified so far:

1. increment/decrement buttons on numeric text input A11y labels on increment/decrement buttons of numeric are not localized #617
2. action menu button in table cells Provide an action menu within a table cell #859
3. sort icon in table header (and soon other icons from UX Design for basic column/row interactions #885 like grouping, collapse all, column menu)
4. banner and tooltip severity

This will also inform related work like the following, though the solution might be different:

1. Table allows configuration of icon column type #1013
2. icons as the primary content of a table column header

Other Labels in Nimble Components

We also have other labels in Nimble components that will need a way for clients to localize them, such as the banner dismiss button, buttons (expand/collapse group, collapse all groups, etc) in the table, and menu items in the table.

Goals

1. Document policy about when providing this content is necessary
2. Decide on an approach that's consistent across components
3. Document that approach
4. Ensure the work to adopt the approach for existing and known future use cases is tracked

Possible Implementations

See HLD: #1272

Tasks

• Write HLD
• Create nimble-label-provider-core and nimble-label-provider-table, and uptake them in nimble-components
• Add label provider integration for Angular and Blazor
• Remove banner dismissButtonLabel (obsolete due to dismiss label on LabelProviderCore)
• Revisit per-component accessibility notes doc and try to document them in Storybook instead

[mollykreis]

We need to make sure that the solution is scalable because some components, such as the table will have many strings that need to be localized. For example:

• label & tooltip for Collapse All button
• label & tooltip for Collapse Group/Row button
• label & tooltip for Toggle selection of all rows checkbox for whole table & group rows
• label & tooltip for Toggle selection checkbox
• Menu item text for items in the column menus -- Sort ascending, Sort descending, Group by column, Size to fit, etc

[rajsite]

Options brainstorming:

Slots

Create slots per localized string on the element.

<nimble-table>
   <span slot="collapse-all-button-label">Hello World</span>
</nimble-table>

Pros:

• Useful for mixed content (if that is even needed, maybe not?)
• Can maybe make shareable slotted content within a framework
  • Angular: Create a shared component that emits elements with those slots
  • Blazor: I expect a blazor component written that way would work too
• Slots can have default content easily

Cons:

• DOM gets littered with many additional elements for providing localized strings
• Lots of duplicated slotted content / elements. Have to emit into every table element as children.

Attributes

Create attribute per localized string on the element.

<nimble-table
    collapse-all-button-label="Hello World"
></nimble-table>

Pros:

• Easy discovery of available properties? Type checked in Angular at least

Cons:

• Maybe not as easy to share / reuse attribute configuration?
  • Angular: Might need to write a custom directive that will emit the attributes onto the host. I think that works
  • Blazor: ?
• Lots of duplicated attributes. Have to emit into every table element as children.
• Only text content (maybe that's okay)

Design Tokens

Conceptually the localized strings are very similar to the sharing pattern of Design Tokens. Vast majority of the time you want to use the same value (increment button text or collapse button text is not control instance specific) but want to adjust to a global config, i.e. theme or language. But also want to be able to override for specific controls as needed.

Create non-css property design tokens, similar to the theme and direction design tokens.
Use the theme-provider to define the value.

<nimble-theme-provider
    table-collapse-all-button-label="Hello World"
>
<nimble-table></nimble-table>
</nimble-theme-provider>

Pros:

• Easy discovery of localized string configuration. They are all on the theme-provider.
• Can configure once for the whole page in one spot, does not need to be per control. Much fewer duplicated attributes / slotted elements in the page.
• Can override for specific elements as needed by wrapping in a theme-provider.
• Can configure to be attribute or slotted on the theme provider. But if don't need mixed content then attribute makes sense.
• User provided control-specific content should still be provided via attributes / slots. This is for control provided content (the table control defines the collapse button, not the user).

Cons:

• Abuse of the tokens system / not intended use-case?
• Maybe not very extensible? Only nimble-components defined within nimble can add new attributes to the theme-provider.
  • Custom columns cannot plugin new properties they may need on the theme-provider. Maybe not a big deal? Then can just use attributes / slots? The custom columns we offer directly from nimble could register their localized strings on the theme-provider...

[atmgrifter00]

As part of this PR, we are lowering the threshold for the Lighthouse Accessibility score. This is to allow the collapse-all button to be submitted without it having a localizable label. When we address this issue we need to re-up the threshold to 90.

[jattasNI]

The theme provider is a cool idea. Another pro is that we could likely single-source the strings in a way that each SLE app doesn't need their own list that would need to be updated every time Nimble adds a new string. For example, we could create sl-theme-provider in systemlink-lib-angular with a child nimble-theme-provider that has all the strings tagged for i18n.

half formed brainstorming👇

That made me realize that it would be cool to have a way for apps to get a list of English Nimble strings that need to be translated. Ideally that list could be imported into the app's localization infrastructure so that they'd automatically get the English version, automatically trigger translation to other languages, and automatically pick up new strings that we add.

How do Angular apps extract strings from their dependent libraries? Could we mark up nimble-angular in the same way we do systemlink-lib-angular and have apps translate the strings inside it? Then it'd be nimble-angular's responsibility to consume the translated strings to configure each component, possibly using one of the approaches above. (I'm not sure when this code would run)

For Blazor, is there a way we could publish a resx file of English strings for apps to translate and then have NimbleBlazor use the translated resx files?