Add internationalization support for human readable labels

[ianbjacobs]

The Internationalization Working Group has raised concerns about lack of Internationalization support for two strings in the specification (see issues #948 and #951).

I agree that the specification should support internationalization.

I believe the following is deployment reality:

• In most cases, language context from the document will suffice for the proper representation of the two strings. That is: I believe that explicit metadata for these strings will rarely be needed.
• These strings are either rendered in the browser "sheet" or in "first party" payment apps (e.g., Google Pay and Apple Pay). These strings are not passed to Web-based payment handlers (through Payment Handler API) and, I believe, not passed to "third party" Android native payment handlers. (There are no third party payment apps with Safari.)
• I also believe that most real-world uses of payment request API involve "skipping" the sheet. That is: calls to Payment Request API involve a single payment method and a single payment app matches, so the browser launches the payment app directly without displaying the sheet. Thus, in practice, rendering these strings in the sheet is rare.
• In Chrome the sheet has been used as part of built-in support for Basic Card. However, Chrome has signaled that they plan to deprecate their built-in support for Basic Card, so that use of the sheet is likely to go away. The Web Payments Working Group has also retired the Basic Card payment method specification.

Summary: In practice these strings are used almost exclusively used by the Google Pay and Apple Pay native apps.

Other observations:

• The Web community is working on a platform-wide solution ("Localizable").
• I believe that browser vendors will consider it a low priority to add support for features that will be rarely necessary and for strings that are not directly handled in the browser (but are passed to a small number of native applications).

Given this context, the current pull request seeks a balance:

• Recognize more visibly the need for internationalization support in this specification. Indicate via Candidate Additions [1] that two dictionaries lack "language" and "direction" members. We can continue to work with Google and Apple on support for these features in Google Pay and Apple Pay.
• Indicate that the Working Group is monitoring the Localizable discussion. It may turn out that a platform-wide solution is preferable to a one-off solution; we don't know yet. We have to consider both backward and forward compatibility in determining how to modify the spec in the future.
• Because these features are expected to be used rarely in the near term, allow the specification to advance to Recommendation with the Candidate Additions.

[Added after posting: if people disagree with the above characterization, please weigh in on that. Thanks!]

I look forward to feedback from @aphillips, @r12a, and the Internationalization Working Group, as well as @marcoscaceres, @stephenmcgruer, @rsolomakhin, and @nickjshearer.

[1] https://www.w3.org/2020/Process-20200915/#candidate-addition

The following tasks have been completed:

• [✅] Confirmed there are no ReSpec errors/warnings.
• Modified Web platform tests (link)
• Modified MDN Docs (link)

Implementation commitment:

• Safari (link to issue)
• Chrome (link to issue)
• Firefox (link to issue)
• Edge (public signal)

---

Preview | Diff

[marcoscaceres]

I don't think it's sufficient to just state that dir and lang will, be added... we need to actually specify them properly, like saying if dir will be an enum, and if an invalid language tag will throw (I guess that's part of whatwg/webidl#1025).

We can keep building on this pull request tho.

[marcoscaceres]

Here is a concrete plan:

• First: get agreement on platform wide dir and lang definition in No "Localizable" type whatwg/webidl#1025
• Based on No "Localizable" type whatwg/webidl#1025, update this spec to do whatever we decide there.
• If it's adding dir and lang, add them to the spec here.
• File bugs on implementations to see if we can get implementation commitment (I can jump into WebKit and/or Chromium if needed).

[ianbjacobs]

@marcoscaceres, quick clarification regarding your plan. Are these steps you recommend after publication of the Rec with this pull request integrated?

[marcoscaceres]

After Rec, as these are additions for a Recommendation.

[stephenmcgruer]

I'm ok with this approach. I don't think I agree with Marcos' comment that we need to include how lang and dir would work in detail at this point, but I might be persuaded if you can explain your reasoning @marcoscaceres :)

(I also don't mind if we do include details, if Ian wants to do the extra work.)

[marcoscaceres]

I might be persuaded if you can explain your reasoning @marcoscaceres :)

So, we wouldn't merge this until after REC, and we would only merge this if our group's criteria is met: we would fully spec this out, add tests, and get implementation commitment (same as any feature we've added to the spec in the past).

[aphillips]

I think this covers the need to call out a potential change while we figure out whether to make it and what form it should take.

[ianbjacobs]

Based on joint I18N/WPWG discussion today [1] I anticipate that we will not add dir/lang to Payment Request. I believe there is now support for publishing the Recommendation with informative hooks that indicate that internationalization for these two strings needs to be fixed and that we are part of a Web community discussion about how to do that with a platform-wide solution. I took an action to work with @r12a on text for the specification.

[1] https://www.w3.org/2021/10/26-wpwg-minutes.html#t03

[ianbjacobs]

@r12a and @aphillips, I have updated this pull request based on the 26 Oct joint discussion. Per @r12a's comments during the meeting, I have characterized this as (1) a fix and (2) pending progress on the platform wide solution. I welcome your review of this and any suggestions.

[marcoscaceres]

I’m approving these, but I’d like to go on the record that I disagree with the additions as they might set false expectations for readers.

I am broadly supportive of i18n solutions, but if OS-level payment handlers don’t ever end up supporting dir/lang (and there is no implementation backing), then there is not much the W3C or working group can do about that (we can “recommend” things, but we can’t force anyone to implement them).

I hope that changes in the future through real-world demand. I would have preferred we continue to advocate for the better i18n support as we’ve done with other features in this specification: through close collaboration with implementers and sites/services that are deploying the API at scale.

[aphillips]

The I18N WG reviewed this PR in our teleconference of 2021-11-04 and I drew an action item to approve it.

[ianbjacobs]

@aphillips, many thanks to you and the I18N Working Group for working with us on this and other issues. We really do appreciate the engagement.