Availability values "no", "readily", and "after-download" might be unclear to non-native speakers

[aphillips]

Various locations in the readme, including:
https://github.com/WICG/translation-api/blob/main/README.md#for-a-known-source-language

We do not intend to force every browser to ship language packs for every language combination, or even to support translation at all. It would be conforming to implement this API by always returning "no" from canTranslate(),

The value for canTranslate() uses English keywords or phrases and some of these ("readily" and "afterDownload") are somewhat idiomatic. The justification for not making this method return boolean type values true and false is that there is a third value afterDownload and that using the boolean keywords would be inconsistent with JS practice (for a variety of reasons).

I would still probably prefer something more like true/false/download or perhaps yes/no/downloadRequired. The values yes and no might be consistent with values for the not-exactly-related attribute translate in ITS.

[domenic]

In general JavaScript enums are not internationalized, so this issue is a bit surprising. E.g. other platform enums that are similar are

enum DocumentReadyState { "loading", "interactive", "complete" };
enum CanPlayTypeResult { "" /* empty string */, "maybe", "probably" };
enum TextTrackMode { "disabled",  "hidden",  "showing" };

I don't recall any requests to internationalize these, or other, JavaScript enums.

As you note, a true boolean is not possible here. Given that, I think it would be pretty surprising to use the string "false", which in JavaScript is truthy. So I like using "no" instead. (Although, see #7.)

And I think "readily" is more accurate than the string "true", as for both the readily-available and after-download cases, it's "true" that you can translate in this browser. It's just a matter of whether you can do so readily, or only after a download.

I don't think I understand the relevance of ITS. It seems to be an XML vocabulary, not a JavaScript API?

[aphillips]

I probably titled this wrong. By "internationalized" here, I do not mean "localized into different languages". What I'm trying to get at by bikeshedding the value names (and let's stipulate that I am bikeshedding) is...

Users of JS APIs are generally software developers and thus have some familiarity with English. However, fluency varies greatly. To ensure the users understand an API, enum values should be chosen that do not depend on English idiom, humor, or other interpretation. In this case, I think the term readily is unclear, especially to non-native speakers.

In your list of examples, most of them are fine, given that the specific definition of each enum term is likely to be in the spec and the terms are relatively distinct (knowing something about the Web platform, I can guess what they means). CanPlayTypeResult stands out as less good, because maybe and probably both mean roughly the same thing with probably implying yes more strongly. Non-native speakers might not get it.

I cited ITS because it describes attributes related to translation that are commonly used in this space--but also because we took some of the features of ITS and incorporated them into HTML, notably the translate attribute, e.g.:

<p translate=yes>Do not translate HTML keywords like <span translate=no lang="zxx">span</span>.</p>

So my thinking was "if translate=[yes|no] then why not canTranslate()==[yes|no|downloadRequired]?"

[domenic]

I've proposed some renames in webmachinelearning/writing-assistance-apis#29 which should address the issue of comprehensibility by non-native speakers.

(Sorry that this issue is spread out over multiple issue trackers... I'm using that one because it's the first one I've written a formal spec for. But the intent is to align the terminology and API surface across all the AI APIs.)

[domenic]

The changes have now been made!

[aphillips]

@domenic The changes in the writing-assistance-apis PR look good to me. Thanks!