Change text for description of GeolocationPositionError.message attribute

[himorin]

In GeolocationPositionError interface, GeolocationPositionError.message attribute is stated as:

The message attribute MUST return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

This description specifies that this attribute is for developers but never for other use including paste onto user interface, but has words like "describing" or "primary".
We're just being careful here because we want to make sure that it's not necessary to concern ourselves with language declarations, bidi labelling, or alternative language choices. We understand that your error messages will be short labels rather than natural language text.

Proposal:

The message attribute MUST return an error message indicating the details of the error encountered and informed by code attribute. This attribute is intended for debugging and developers SHOULD NOT use it directly in their application user interface.

[reillyeon]

I don't understand how the use of the words "describing" or "primary" could lead to this confusion.

I do prefer the proposed text because makes it clearer that application logic should use code for decision making and message only for debugging purposes.

[xfq]

I don't understand how the use of the words "describing" or "primary" could lead to this confusion.

If the error message "describes" rather than "indicates" the details of the error, then it is considered natural language information rather than a short label, and should have associated language metadata.

The word "primary" means the attribute can also be used in situations other than development/debugging of the application, which implies that the message attribute may contain natural language information for users of the application.

See the string-meta document for more information about language and direction metadata.

[reillyeon]

Is there a reference document for these definitions? The intent of the original text is the opposite of this meaning. It says, "This attribute is primarily intended for debugging." The word "primarily" is being used to emphasize the intended purpose (debugging) and not to indicate an additional purpose.

[xfq]

Is there a reference document for these definitions?

If you mean the definition of "describing" or "primary", I think they're just English. According to my understanding of the discussions in the i18n WG meeting (the meeting minutes are relatively concise, sorry for that), the word "primarily" means the most important purpose is for debugging, and there may be secondary purposes.

Maybe @r12a can describe (no pun intended) his intention better?

---

(Coincidentally, I just saw the word here: https://www.w3.org/2020/06/machine-learning-workshop/#goals )

[r12a]

@reillyeon the main purpose of this issue is to check whether the value of the message attribute is something that may need to be localised. We weren't sure about the answer to that question because of the wording of the text.

You say that the value is intended (primarily) for debugging, but you didn't say that this isn't natural language text. So i infer from that that the value will be a natural language description (presumably explaining the value of the code attribute?), and that you expect that anyone doing debugging will speak the language in which that value is written (English?), so that there is no need to translate it. Is that correct? (We don't normally assume that if you are describing something in natural language text that it doesn't need translating: we assume that the purpose of adding an explanation in natural language is to help the person who reads it better understand something, however, we don't think that people who develop apps will necessarily speak English(?) well enough to benefit from the explanation given, even though they may use English keywords. (We are currently working with another group that wants to write certain things in Chinese.)) You may argue that that's not an issue, but we need to ask the question.

But the main point we are trying to clarify here is what exactly those message attributes will contain. Do you have some examples? (Apologies if there are some in the spec that i missed.)

[reillyeon]

Your assumption is correct. The message attribute is a natural language description of the code attribute and may contain implementation-specific additional debugging information. It is intended for developers and not users and so should be provided in the language used for other developer messages such as Javascript console warnings.

In the Chromium implementation the message attribute is set to strings such as "User denied Geolocation" and "Geolocation has been disabled in this document by Feature Policy."

[marcoscaceres]

@reillyeon, I'm inclined to agree with @himorin and the i18n folk's proposal: the "primary" implies, or doesn't rule out, that there could be a "secondary" use (making the current text accidentally slimy).

[marcoscaceres]

How about:

          <p>
            The <dfn>message</dfn> attribute is a developer-friendly textual
            description of the <a>code</a> attribute.
          </p>
          <p class="note">
            The purpose of the <a>message</a> attribute is debugging to assist
            with debugging and it's not intended to be shown to end users.
          </p>

[xfq]

If it's natural language text, then per guidance from the i18n WG language and direction metadata are needed. As @r12a said, people who develop apps do not necessarily speak English well enough to benefit from the explanation given.

[marcoscaceres]

If it's natural language text, then per guidance from the i18n WG language and direction metadata are needed.

It's not. Exceptions are usually just thrown in unlocalized and in English. When they are localized, it's done as courtesy or as thing browsers compete on (developer experience).

[reillyeon]

I was initially surprised that console messages weren't localized but then it was pointed out to me that doing so could make them harder to search for online.

[marcoscaceres]

Yeah, we've actually moved away from localizing them also... probably for the same reason.

[xfq]

The developers do not speak English well enough can only search in a forum (or search engine) using the English message, and then read discussions in their native language. If there is an error message in their native language, they may be able to solve the problem themselves without searching.

Is it possible for the browser to provide two languages to the user (English and the user/developer's preferred language)? This not only solves the searchability problem, but also make the error message easier to understand for people who are not quite familiar with English.

In this case, even people who speak English can choose to search in their native language, search in English, or search both to see more results.

[marcoscaceres]

@himorin, @xfq let me know if #51 is a suitable fix.

[xfq]

I (as both DAS and i18n WG participant) don't want to block the REC publication, so I think it's a suitable fix for now, but note that the i18n WG is writing some guidelines for error message handling that may affect this attribute in the future.

[chaals]

Having watched this issue for quite a while, this seems a very disappointing example of deciding that it's inconvenient to support internationalisation so we don't care enough to fix it.

The problem os making sure it is possible to search for a particular error message is pretty clear, but being able to tag something this deterministic with an identifier as well as a message that people can read is literally what the web has been doing for 30 years (and it wasn't actually a revolutionary aspect back then).

It is clearly possible for developers to look up the text of an english message by copying and pasting it into some other system (a translator, finding it as a key in the documentation so long as documentation in languages the developer is comfortable with actually includes it as a key, ...). It's just that it does discriminate against non-english-speaking developers, which reflects pretty badly on the commitment to enabling the world to participate equally.

[marcoscaceres]

I don't think the API discriminates. The .code value is perfectly i18n agnostic (in a good way). What we should do is deprecate the .message attribute, as it's not intended to end up being shown to the user - that last thing anyone wants is browser engineers writing user-facing error messages!

If we do anything, we should expose an error .type attribute, to an enum that more easily gives access to what the error was (e.g., "timeout", "user_denied", etc.)... this would just be a slightly friendlier/less-ugly version of .code.

[xfq]

(i18n WG actioned me to reopen this issue.)

Even .message is not intended to be shown to end users, it is still a piece of natural language text, not a "plain string" (see string-meta) value, and language information is needed. i18n is OK with removing the .message attrubite and using .code instead, but if we keep .message, we'll want to discuss further because we know these leak.

See i18n specdev for related guidelines.

[r12a]

Could the geolocation folks clarify which direction they plan to go, from the alternatives above?

[marcoscaceres]

We can't remove .message as it would potentially break too many sites. And there is little incentive to update implementations to do anything meaningful with .message. I think the best we can do is what we already do: in the spec, we discourage its usage and note that it's a legacy thing.

[xfq]

in the spec, we discourage its usage and note that it's a legacy thing.

I might be missing something, but I don't think the note in https://w3c.github.io/geolocation-api/#message-attribute says the usage of .message is discouraged. It only says it's not intended to be shown to end users.

[marcoscaceres]

I might be missing something, but I don't think the note in https://w3c.github.io/geolocation-api/#message-attribute says the usage of .message is discouraged. It only says it's not intended to be shown to end users.

The "it's not intended to be shown to end users" is what I meant by discouraged. That is, it's discouraged as a means to convey any useful information to anyone but developers for when they are debugging.

[marcoscaceres]

@xfq, I've made the note stronger and provided more guidance for developers to use .code instead. It now says:

NOTE: Don't show .message to users!
The purpose of the message attribute is to assist with debugging - as such, they probably won't make any sense if shown to an end user. Please use the GeolocationPositionError's code attribute to create user-friendly localized error messages.

[marcoscaceres]

Made a few more tweaks https://w3c.github.io/geolocation-api/#message-attribute

[aphillips]

(I drew an action from I18N to respond to this thread)

We have an on-going discussion/debate about the problem of error messages in protocols. I'm going to summarize here the gist of our debate, which is partially mirrored by the above. Apologies for what promises to be a longer note.

In general, I18N has a strong preference that any natural language text conveying human readable messages or human readable content be associated with language and direction metadata. Where this metadata is missing, the processing or display of the text might be compromised.

We also (separately) prefer that anywhere that customer experience (CX) messages appear that there be mechanisms for negotiating the language/locale or for localizing the resulting display. These are both fairly fundamental tenets of I18N and I don't think they're controversial on their face.

Error messages fall into an interesting gap. Usually the intention of an error or exception message is that it convey debugging information to a software developer. And it is fairly common in different niches of the industry not to provide localization of exception messages (most JVMs for example). A few users cite practical reasons why localization of error messages can turn out to be a barrier--generally when the message is insufficiently good to explain the problem and where being able to search the text of it produces results in the developer's preferred language is more helpful. Protocol and API designs are often similar to what geolocation has done (and indeed the inclusion of .code is a step above just having a string for the error). But...

Error messages are messages and they are intended for humans (the existence of .code would otherwise be sufficient). In many cases, the error message encompasses all of the additional information about what went wrong and, in some cases, the caller is obliged to show the message to the actual end user because there is no other way to convey to the customer how to fix the problem ("Your credit card has expired"; "The latitude value 10484977 is too large" [oops, forgot the decimal point]; etc.). Localization of these types of messages is actually a good thing and may even be obligatory in some applications. There are also places where implementers build and run their system entirely in e.g. Russian (so one can't assume that the message is always in English, eh?)

The statement that "we don't want developers writing messages" is flawed in a couple of ways: (1) we often have developers writing resource files containing human CX messages and (2) messages that matter to end users are more likely to be written by the CX designer and only implemented by the developer. When the error message is the CX it will be handled with greater care perhaps. The existence of poorly written/implemented messages (which includes English ones!) is not a reason to disallow a localized experience where one is possible or desirable.

Ultimately the problem here is that the geolocation API (or other APIs) cannot know at design time how a given error or message will be consumed and displayed to the customer. The assertion that the message never contains information of value to the end user is probably false: if the message never conveyed additional information, the geolocation client could just look it up from the .code or the developer from the spec.

There are counterarguments and the discussion in the I18N WG has been about whether and to what degree making the above recommendations is helpful vs. including a note such as @marcoscaceres quoted just above. I know from recent experience raising the bar on writing localizable exceptions in my day job that breaking "years of tradition" from developers is extra work.

[marcoscaceres]

@aphillips, I fundamentally agree with the logic and rationale - and I too have done work localizing DOM exceptions, so know exactly where you are coming from. However, at this moment, we are treating Geolocation as a "revised recommendation" to get it to retroactively match what is currently shipping in browsers and not adding new spec features.

We hope to add enhancements in future versions, once we get this spec to become a "living standard" under the Process 2020. I think at that point, we should add:

"User agents SHOULD localize the .message attribute to match the document's language.".

Or something similar. But adding that now would be deceptive, as no user agent localizes the error message and there is currently no plan from any implementer to localize these error messages. Thus, I'd prefer we work with implementers to get them to commit to localizing error messages, rather than put aspirational conformance requirements that we know are just going to be ignored. This is why, in the note, I explicitly call out the terrible situation at the moment:

To make matters worse, the text of these error messages is not localized.

So, yes, we will come back to this... and we should probably do this in WebIDL too, as that's the source of most DOM Exceptions. But we will opt not to do it now.

[marcoscaceres]

@aphillips just so you concretely see what I mean:

WebKit's hard coded error strings:
https://github.com/WebKit/WebKit/blob/c80365976bcc5917dde4c1a37eb629800d866a47/Source/WebCore/Modules/geolocation/Geolocation.cpp#L52-L55

And here are Gecko's:
https://github.com/mozilla/gecko-dev/blob/master/dom/geolocation/GeolocationPositionError.cpp#L24-L38

And here are Blink's:
https://chromium.googlesource.com/chromium/blink/+/master/Source/modules/geolocation/Geolocation.cpp#47

[marcoscaceres]

I'm going to go ahead and close this as addressed from us.

@aphillips, @himorin, @xfq, or other i18n folks, please let me know if you are satisfied with the resolution (changes at https://w3c.github.io/geolocation-api/#message-attribute and the rationale why we can't take this further at this point).

[aphillips]

I think this is a chicken-and-egg problem: browser vendors have no incentive to change something that is spec-compliant, the spec has no incentive to support something browsers are not currently doing. The presence of I18N bugs in the browser code bases is sad, but not a really compelling argument: each of the browsers has a localization framework and could localize the messages if they cared to. (Localizing them to match the document language is probably the more difficult problem).

I'm not overjoyed with the text of the note either. While it does describe the current state of affairs, it makes the claim that the message is "not localized" (that might not always be true: a browser vendor could localize it, even if they didn't support document language). As noted elsewhere, the code attribute can't convey the same level of debugging information as the message. I'd rather geolocation adopted a more forward looking set of advice, even though I accept that you're not going to add lang/dir attributes just now. Perhaps:

NOTE

The purpose of GeolocationPositionError's message attribute is to assist developers with debugging. 
For legacy reasons, this attribute does not supply language or base direction metadata and, in most
user agents, is only localized into English. Consumers are advised to leverage the code attribute to
create a localized experience. Implementers should provide for localization of the message attribute
using the caller's language. Future versions of this specification may add support for language and
direction metadata as required by [[STRING-META]] and [[BP-I18N-SPECDEV]].

I have not yet discussed this comment with the I18N WG, who may disagree with me.

[marcoscaceres]

I think this is a chicken-and-egg problem: browser vendors have no incentive to change something that is spec-compliant, the spec has no incentive to support something browsers are not currently doing.

I don't know if it is a chicken/egg problem, tbh. Mandating requirements in the spec is not a motivator either, as without real world incentives to make a change (e.g., a large web site really needs this or it's causing issues at scale), there will be limited incentive to invest in doing the localization of DOMException messages. From experience, across the entire platform, there seems to be little motivation to localize DOMException messages overall... not a good thing, but reflects current reality - but that's something we need to maybe take on at the source (i.e., WebIDL, HTML, DOM spec).

From experience, browsers tend to focus their energy localizing end-user facing strings instead, as they impact vastly more people.

each of the browsers has a localization framework and could localize the messages if they cared to. (Localizing them to match the document language is probably the more difficult problem).

This is true. And you are spot on about the "cared to", but it's a matter of priority... as in they care to prioritize localizing other strings.

I'm not overjoyed with the text of the note either. While it does describe the current state of affairs, it makes the claim that the message is "not localized" (that might not always be true: a browser vendor could localize it, even if they didn't support document language).

As Geolocation transitions to a "Living Standard", it's true per the implementation links above. If that were to change in any engine, we would update the spec to reflect the new reality.

Re the updated note - it reads much better, so I'll take add your modifications. However, I'd be hesitant to add:

"Implementers should provide for localization of the message attribute using the caller's language."

As that's clearly a conformance requirement.

I'm also a little hesitant to add:

Future versions of this specification may add support for language and direction metadata as required by [[STRING-META]] and [[BP-I18N-SPECDEV]].

Without first discussing those with implementers. As you know, I'm really supportive of the things being mandated in STRING-META (and hope Localizable will become core infrastructure in WebIDL itself), but I've yet to review BP-I18N-SPECDEV.

[marcoscaceres]

Sent #72 - thanks again @aphillips for the rewording suggestions. Looking forward to continued improvements to the platform around this topic.

[Tom333Trinity]

I can only view i18n via the scope blowout of the Geolocation API ERROR spec as a classic case of the tail wagging the dog.

Should we not close this topic in favour of more appropo fora such as https://www.w3.org/International/ ?

@jyasskin What are your thoughts on this? Redirect to WICG?

PS. I much prefer, and think it is more accurate, to use the Oracle "Globalization" or g11n. And its symmetry with a11y looks cool! All the big issues soleved.

[chaals]

IMHO

This is the forum for development on the API. Making it functional for the world at large is a core part of what W3C expects for any piece of work. So no, this issue being dealt with here isn't a tail wagging a dog, it is another example of a problem you have spent 5 years complaining about, in this case being handled correctly, generating some real expectation that the problem will this be fixed by and by.

"i18n" has been the term used along with "l14n", and globalisation carries assorted baggage that I suspect will just lead to distractions.

[marcoscaceres]

As @aphillips mentioned above, we have the STRING-META and BP-I18N-SPECDEV documents for generalized solutions and guidance to this particular i18n problem - with the aim to push a solution to WebIDL, which is the spec that governs DOMExceptions and the .messages that goes with those exceptions.

Geolocation is unfortunate in its legacy design, in that it uses its own error handling system. Remember, this was designed over a decade ago, and it seemed like a good idea at the time!... same with Indexed DB... we know better now.

Pie in the sky idea right now but... if we do end up revising how Geolocation works (e.g., by turn it into a Promise-returning API), then we can address these problem fully at that time.

[marcoscaceres]

Merged #72 in prep for publication of FPWD... happy to revise further after FPWD tho!

[marcoscaceres]

Moving discussion to WebIDL spec, so we can have a general solution for the platform: whatwg/webidl#996