Localization and string metadata for descriptions

[aphillips]

2.2 Describing what is being paid for
https://www.w3.org/TR/2020/CR-payment-request-20201203/#describing-what-is-being-paid-for

Example 2 contains this:

const details = {
  id: "super-store-order-123-12312",
  displayItems: [
    {
      label: "Sub-total",
      amount: { currency: "USD", value: "55.00" },
    },
    {
      label: "Sales Tax",
      amount: { currency: "USD", value: "5.00" },
      type: "tax"
    },
  ],
  total: {
    label: "Total due",
    // The total is USD$65.00 here because we need to
    // add shipping (below). The selected shipping
    // costs USD$5.00.
    amount: { currency: "USD", value: "65.00" },
  },
};

The value label contains natural language text with no language metadata or base direction information. The same usage is found in other example sections that follow. I18N recommends that there be a means of providing this metadata so that the document's processor can display the value correctly.

This comment is probably a duplicate of #327. It is also related to #946

[aphillips]

I'm going to add w3c/i18n-activity#1359 and w3c/i18n-activity#1357 as additional examples to this issue instead of cluttering your repo with additional specific issues. I've replicated the text of these issues in this comment.

---

14.1.2 PayerErrors dictionary
https://www.w3.org/TR/2020/CR-payment-request-20201203/#payererrors-dictionary

 const payer = {
  email: "The domain is invalid.",
  phone: "Unknown country code.",
  name: "Not in database.",
};

Example 13 shows the payer errors dictionary being used to convey unlabeled natural language string values. As noted in other comments, there is no language negotiation scheme in place. There is also no metadata here to help with display.

---

PaymentShippingOption dictionary
https://www.w3.org/TR/2020/CR-payment-request-20201203/#paymentshippingoption-dictionary

label member
A human-readable string description of the item. The user agent SHOULD use this string to display the shipping option to the user.

The label member has no language or direction metadata. Further, it cannot be localized by providing reference to a multilingual construct of some sort. There doesn't appear to be a language negotiation mechanism so that a language can be requested.

The SHOULD might be problematic vs. allowing the user agent to wrap the provided display string with a localized value, i.e. it could say something approximately like:

The user agent SHOULD use this string (or a localized version available to the user agent locally) to display the shipping option to the user.

[marcoscaceres]

Based on #956, leaving this open to address in a future version of the spec.

@aphillips, for our records, could you please indicate if i18n is satisfied with this course of action?

Please add any other labels the i18n WG needs to track this going forward.

[xfq]

Note that we don't remove the -needs-resolution label even if the WG issue is closed or deferred to the next version, because it is easier to see which issues were raised by the i18n WG.

See https://www.w3.org/Guide/documentreview/#working_with_horizontal_review_labels for more information.

[marcoscaceres]

Thanks @xfq. I've updated my comment above.

[rsolomakhin]

WebAuthn spec encodes the language code and text direction into the string itself using unicode. Is that a common practice that we could use here?

[marcoscaceres]

WebAuthn spec encodes the language code and text direction into the string itself using unicode. Is that a common practice that we could use here?

wait! what?!?!?! no 🤦‍♀️.

[r12a]

The i18n WG will be looking into that section in the WebAuthn spec, which seems to have been added without our review. On first sight it appears to contain many issues. Please don't copy the approach until we have had time to look more closely.

[aphillips]

We are continuing to work with webAuthn on correcting their metadata encoding mechanism--a mechanism we do not recommend be used anywhere else. In reviewing these issues as part of your pending CR request, I think this has to be regarded as a duplicate of #327. Since these issues remain unaddressed in the pending CR (@marcoscaceres's changes were backed out or not included in the spec), I can't say that we're satisfied yet.

[ianbjacobs]

Hi @aphillips,

Following our previous discussion we added this note to the spec:
#956

That note is in the current draft for which we've requested advancement to Proposed Rec.

It was my understanding from previous conversations that this note was sufficient for v1,
and we'd return to the question post v1. I recall that there was shared agreement that
we would not be adding dir/lang information to the displayItems dictionary in v1.

(@marcoscaceres, please also weigh in.)

[aphillips]

There are really two problems here. One is the lack of a language negotiation mechanism (which is what PR#956 seems to be about??), which we all agree it out of scope for v1. In your email about "Preparing to advance PR API 1.0 to Candidate Rec" you reviewed all of the open issues (thanks for that!) you called out:

* Add dir/lang member on dictionaries whose content is displayed in browser UI
  https://github.com/w3c/i18n-activity/issues/251

  We closed this with Pull request 956:
  https://github.com/w3c/payment-request/pull/956

  Cf. Addison’s comments, including:
  https://github.com/w3c/payment-request/pull/956#discussion_r634453183

(Notice that my response focuses on the localization mechanism)

The other is lack of language/direction metadata. All of those threads appear to be dangling, at least in github. It's possible that we discussed this via email somewhere that I haven't spotted yet. But my review this morning seems to suggest that a pull request might be waiting on our String-Meta doc to provide the necessary reference or that some other mechanism would be agreed. I thought at one point that Marcos had addressed with a pull request, but that seems to have been pulled back. The recent discovery of webAuthn's problematic encoding (see above) fell out of that too.

Probably this is too late to do anything about and possibly you're right we agreed to it, but it seems like we all overlooked that lack of a localization mechanism != lack of metadata fields? Hence today's comments...

[marcoscaceres]

But my review this morning seems to suggest that a pull request might be waiting on our String-Meta doc to provide the necessary reference or that some other mechanism would be agreed.

That's correct. I was banking on us solving this at the platform level, via WebIDL (or Infra). We have this same problem everywhere we use dictionaries like this, so I'd like us to solve this for the whole platform.

I thought at one point that Marcos had addressed with a pull request, but that seems to have been pulled back. The recent discovery of webAuthn's problematic encoding (see above) fell out of that too.

That would be issue:
w3c/string-meta#54

And something we take to WebIDL.

[r12a]

There are really two problems here. One is the lack of a language negotiation mechanism ... The other is lack of language/direction metadata.

The note after bullet point 18 at https://www.w3.org/TR/payment-request/#show-method is a step in the right direction (thank you), but it munges these two things together in a way that is unclear. Here is a proposal for 2 separate notes, that describe the 2 issues. Since you appear to be in a hurry, i am posting some suggested text now, before the i18n WG has a chance to review it, but i will ask the group to follow up after our telecon later this afternoon.

Note: Metadata for international text display
The API does not currently provide a way for developers to declare the language and base direction for any item of text in the payment sheet that is presented to end users. Instead, the API relies on information inherited from the document. The working group is considering how to add this metadata to the next version of this API. In the meantime, issues may arise when using this API to display text in various languages.

Note: Localization of the payments user interface
The API does not currently provide a mechanism for developers to localize information presented to end users. The working group is considering support for requesting a specific localization of the user interface and of individual PaymentItems and user-facing error messages in a future version of this API.

[ianbjacobs]

Hi @r12a,

First, thank you.

We published the proposed recs today. I am very supportive of integrating helpful notes (with support from the Director) in the Recommendation. Thus, there is some time for the I18N WG to review the proposal. Please let us know here if there is support from the WG, and I'll work with the editors to incorporate after Proposed Rec reviews.

[ianbjacobs]

@aphillips, with the adoption of #971, do you remove the needs resolution label?

[r12a]

@ianbjacobs i just closed our tracker issue, so that should fix it.

[frivoal]

From the commit in #971:

The language and direction of the {{PaymentItem/label}} may often be determined from information inherited from the document

May be determined how? For the direction, I'd suggest taking it from the principal writing mode of the document. The language could probably also be taken from the language on the root element, likely with the usual HTML rules for taking the combination of the lang attribute, information from meta elements, and also the protocol (e.g. from HTTP headers) into account.

If additional mechanisms are later introduced to provide more flexibility, they could always override this default, but it seems preferable to make the default unambiguous.

Accidental incorrect detection of the language or direction (and related interoperability problems) can potentially make text somewhat confusing, or even downright unreadable. Using a Chinese font for Japanese content (or vice versa) may present the user with some unfamiliar characters, and going ltr where rtl is expected (or vice versa) can scramble the content.