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