Localization topics to address

[ianbjacobs]

Hi folks,

In light of our discussions with the Internationalization Working Group about Payment Request, I thought it would be useful to take note here of some topics that we should be sure to address in SPC.

• SPC UX localization. In Payment Request we say: "The user interface SHOULD be presented using the language and locale-based formatting that matches the document's document element's language, if any, or an appropriate fallback if that is not available."
• Lang/dir for input strings (e.g., displayName, payeeOrigin).
• Localizability of any error messages.

We'll seek I18N review once a formal Working Draft; this is just to kick off discussion.

[ianbjacobs]

Here is a checklist from the I18N Working Group.

1. If the spec (or its implementation) contains any natural language text that will be read by a human (this includes error messages or other UI text, JSON strings, etc, etc),

• SPC implementations render a modal window that displays human readable information provided by a Relying Party.
• There is also text provided by the browser itself, presumably in the browser language selected by the user.

2. If the spec (or its implementation) allows content authors to produce typographically appealing text, either in its own right, or in association with graphics.

Not part of this API.

3. If the spec (or its implementation) allows the user to point into text, creates text fragments, concatenates text, allows the user to select or step through text (using a cursor or other methods), etc.

Not part of this API.

4. If the spec (or its implementation) allows searching or matching of text, including syntax and identifiers

Not part of this API.

5. If the spec (or its implementation) sorts text

Not part of this API.

6. If the spec (or its implementation) captures user input

Assuming this means "the user inputs some text" then not part of this API. There are "user gestures" to authenticate.

7. If the spec (or its implementation) deals with time in any way that will be read by humans and/or crosses time zone boundaries

Not part of this API.

8. If the spec (or its implementation) allows any character encoding other than UTF-8.

Not part of this API.

9. If the spec (or its implementation) defines markup.

Not part of this API.

10. If the spec (or its implementation) deals with names, addresses, time & date formats, etc

Not part of this API.

11. If the spec (or its implementation) describes a format or data that is likely to need localization.

I don't think that is part of this API.

12. If the spec (or its implementation) makes any reference to or relies on any cultural norms

Not part of this API.

It is possible that the underlying FIDO authentication iconography relates to cultural norms (e.g., display of a fingerprint to mean biometric authentication). SPC does not introduce anything on top of that.

[aphillips]

Don't overlook that PaymentCredentialInstrument dictionary contains a natural language string value (displayName) and thus requires language/direction metadata. While we're discussing backwards-compatible (and somewhat forced) in-string mechanisms for encoding these with webAuthn currently, SPC has no such backwards compatibility limitation AFAICT and should use metadata fields instead.

[ianbjacobs]

Hi @aphillips,

To confirm my understanding of the purpose of the lang/dir metadata information: to enable the browser to properly render in its modal window the information provided by the relying party.

[ianbjacobs]

@marcoscaceres, welcome your thoughts on this.

[aphillips]

To confirm my understanding of the purpose of the lang/dir metadata information: to enable the browser to properly render in its modal window the information provided by the relying party.

@ianbjacobs Exactly so.

[ianbjacobs]

@stephenmcgruer and @rsolomakhin, let's discuss!

[ianbjacobs]

See w3c/string-meta#26

[ianbjacobs]

@rsolomakhin please mention what you'd like to see in more detail

[ianbjacobs]

@ve7jtb mentioned the following: although in general the SPC dialog will be displayed by the browser, it might also be displayed by some other entity (e.g., the OS). In those cases, to avoid error it may be even more important to have well-defined lang and dir as input rather than rely on browser context.

[rsolomakhin]

i18n folks: Could you please provide explicit examples where SPC displays the instrument name incorrectly? You have way more expertise here and I'd love to utilize it. For example:

Browser language: en-US
Page language: en-US.
Instrument display name: <insert name here>.
Instrument display name direction: LTR/RTL.
Instrument display name language-script code: <insert BCP47 here>.
Actual result: <insert screenshot of the incorrect rendering in here>.
Expected result: <describe or attach or what the correct rendering should look like>.

---

When we decide to add the l10n support, there're several possibilities of how to accomplish that:

1. Add extra optional parameters:

instrument: {
  displayName: 'Card****1234',
  language: 'en-US',  // Optional.
  direction: 'ltr',  // Optional.
  icon: 'https://icons.example/card.png',
}

• Pro: Older browsers that do not read the language and direction still get the cleartext displayName that they can read.
• Con: If someone had a pre-existing integration around SPC that hard-coded the number of fields, then they may need to encode the language and direction into their own systemSpecificInstrumentDisplayName field and then parse those fields out before invoking SPC.

2. Make displayName accept a very limited subset of HTML:

instrument: {
  displayName: '<span lang="en-US" dir="ltr">Card****1234</span>',
  icon: 'https://icons.example/card.png',
}

• Pro 1: Only one field is being used for displayName.
• Pro 2: Parts of HTML standard can be re-used.
• Con 1: Feature detection is absent, so the integrators would need to wait for the 99% of deployed browsers to support HTML in displayName, so that they don't display the HTML in the SPC dialog on accident.
• Con 2: It may be difficult to specify the the limited subset of HTML safely.

3. Make displayName accept a JSON string with value, direction, and language fields.

instrument: {
  displayName: '{"language": "en-US", "direction": "ltr", "value": "Card****1234"}',
  icon: 'https://icons.example/card.png',
}

• Pro 1: Only one field is being used for displayName.
• Pro 2: Parsing JSON strings is fairly lightweight, which allows running the parser in a separate utility process, thus increasing safety.
• Con 1: Feature detection is absent, so the integrators would need to wait for the 99% of deployed browsers to support the JSON strings in displayName, so that they don't display the JSON in the SPC dialog on accident.
• Con 2: Defining a new ad-hoc l10n display standard is out of scope of SPC. If other APIs do not use this format, that increases API fragmentation on the web.

4. Utilize @marcoscaceres's new Localizable strings:

instrument: {
  displayName: {language: 'en-US', direction: 'ltr', value: 'Card****1234'},
  icon: 'https://icons.example/card.png',
}

(If I understand how it works correctly.)

• Pro 1: Limited feature detection is possible by calling new PaymentRequest() with the dictionary displayName parameter and checking if the constructor throws.
• Pro 2: If other web standards adopt the Localizable string definition, that would make web development more straightforward.
• Con: If someone had a pre-existing integration around SPC that hard-coded displayName as a string, then they may need to encode the language and direction into their own systemSpecificInstrumentDisplayName field as a JSON string and then parse the JSON string into a JavaScript dictionary before invoking SPC.

---

Option 4 is what I'm leaning toward because of the more sane feature detection and ability to back-port pre-existing string fields that are used fordisplayName.

Integrators and implementers: Please help me to understand your organization's preferences!

[aphillips]

@rsolomakhin Could you have a look at these documents, which might answer some of your questions:

https://w3c.github.io/i18n-drafts/articles/lang-bidi-use-cases/
https://w3c.github.io/string-meta/

You may also want to look at JSON-LD for various JSON-based mechanisms, cf. https://www.w3.org/TR/json-ld/#string-internationalization

[stephenmcgruer]

To give a direction for the upcoming TPAC discussion on this issue: I propose we make displayName a union of String and a Localizable structure, as a backwards-compatible version of option 4. (It would also be great if i18n group gets to a point where Localizable is not something that we have to define before we do this.)

[rsolomakhin]

Aside from Localizable, can the i18n folks please provide guidance on defining alt-text for images that are passed into APIs? For example, should the alt-text have a language associated with them for the sake of the screen reader? Should the alt-text have a direction?

[ianbjacobs]

See related resource in development: https://github.com/aphillips/i18n-discuss/blob/gh-pages/explainers/string-meta-explainer.md

[aphillips]

@ianbjacobs: the official copy is more up-to-date: https://github.com/w3c/i18n-discuss/blob/gh-pages/explainers/string-meta-explainer.md

[aphillips]

@rsolomakhin I18N believes that any human-readable (natural language) string data should have language and direction metadata associated with it, either directly or, failing that, at the document level. APIs should be able to store, forward, and process this information for consumption. Page authors can then use the data to build as rich (or poor) a customer experience as they want.

The HTML img tag's alt attribute doesn't have a way to express the language or control the base direction of the associated string, although, I suppoed in the case of an image tag one might use the lang and dir attributes of the tag itself? Other language-bearing attributes in HTML can't use that workaround/hack, of course. This is a long-standing (and lamented) situation with HTML.

However, APIs might expose the text in other ways than just producing an alt attribute and the information might be consumed by (for example) the screen reader in that way. In the case of an image alt that's pretty speculative, of course. But the page author might use a different approach, such as enclosing the img in a figure and using the figcaption element instead of using alt.

[rsolomakhin]

Thank you for the update, @aphillips!

[ianbjacobs]

See w3ctag/design-reviews#716

[ianbjacobs]

We added payeeName to the specification; we'll want to be able to localize that value as well.

[ianbjacobs]

@aphillips, @r12a, @xfq, we've not heard much news about generalized support for localizable strings in ECMAScript or in a "standalone spec" that could be referenced from SPC, WebAuthn, and other specs that involve JSON being displayed in browser UX.

I've just created pull request #192 based on language that we used in Payment Request API: that lang and dir information can be taken from the document context and used within the browser's native UX. This does not address downstream usage of the data, but I suspect for real downstream interop we would want ECMAScript level support in any case.

Please let us know whether this text would satisfy the I18N WG for version 1 of the specification, or what changes you would find helpful. Thank you!

[ianbjacobs]

@aphillips, @r12a, @xfq, it would be great to hear from you. Could we discuss no later than TPAC? Thanks!

[ianbjacobs]

Closing this issue based on more recent and more specific I18N issues #205 and and #209, as well as discussion with @aphillips during TPAC.

For a more recent I18N checklist, see #202.

Regarding "localized error messages", SPC does not itself define any error messages.