Proposal: i18n-system-languages #569

carlosjeurissen · 2024-03-18T22:52:48Z

This PR adds the proposal for both i18n.getPreferredSystemLanguages() and i18n.getSystemUILanguage() previously called i18n.getOSLanguage(), which all vendors are supportive on as discussed in #252

rdcronin

Thanks, Carlos!

proposals/i18n-getOSLanguage.md

rdcronin · 2024-03-28T16:24:58Z

proposals/i18n-getOSLanguage.md

+```json
+{
+  "name": "getOSLanguage",
+  "type": "function",
+  "nocompile": true,
+  "description": "Gets the UI language of the Operating System. This is different from $(ref:i18n.getUILanguage) which returns the UI language of the web browser.",
+  "parameters": [],
+  "returns": {
+    "type": "string",
+    "description": "An IETF BCP 47 language tag such as en-US or pt-BR."
+  }
+}
+```


nit: I'd lean towards describing these in typescript (for now), since it's a more portable format than Chromium's use of JSON schema. Especially things like "nocompile" are very Chromium-specific.

That said, if other browser vendors are fine with (or prefer) this, I don't feel strongly, since, well, this is obviously good enough for Chromium : )

Agreed, TypeScript would make more sense.

rdcronin · 2024-03-28T16:25:37Z

proposals/i18n-getOSLanguage.md

+  "nocompile": true,
+  "description": "Gets the UI language of the Operating System. This is different from $(ref:i18n.getUILanguage) which returns the UI language of the web browser.",
+  "parameters": [],
+  "returns": {


This implies a synchronous return. Is that a requirement?

(I'm not sure if we'd have the OS language available in the renderer today, unlike the UI language)

In Mozilla Firefox, the OS language is available in the renderer synchronously. In general the motivation to return synchronously is to match i18n.getUILanguage. Having it synchronously is also very welcome to load locale data as quickly as possible for bidi, lang attributes, locale specific files and potentially in the future, passing it to an API like i18n.getLanguageDictionary

rdcronin · 2024-03-28T16:28:32Z

proposals/i18n-getOSLanguage.md

+**Document Metadata**
+
+**Author:** carlosjeurissen
+


This dropped the "sponsoring browser" item here.

That was added to ensure the proposals here don't become a graveyard of aspirational APIs and instead reflect ones that at least one browser is committed to implementing in the immediate future.

I'll need to do some quick investigation into the implementation. If it looks straightforward, I'm comfortable putting Google Chrome as the sponsoring browser.

Added back the Sponsoring browser with a TBD.

I'm supportive of sponsoring for Safari and plan to implement it as soon as we have consensus.

proposals/i18n-getOSLanguage.md

carlosjeurissen · 2024-03-28T18:36:27Z

@xeenon Thanks for reviewing and the willingness to implement this.

@rdcronin Thanks for reviewing and your comments. Most feedback has been implemented in the proposal. Thanks for offering to sponser the feature as browser.

@Rob--W Reading from your comment in the reading notes of Today's (2024-03-28) meeting:

This proposal doesn’t follow the new process. One of the aspects of the new process template is that there should be at least one browser committing to implementing the API.

It was under my impression there was general support for this feature across browsers and the next step would be a proposal. However I understand your concerns regarding ending up with many proposals without browsers moving forward to actually implement them. So I went ahead and created a patch for Firefox.
See: https://bugzilla.mozilla.org/show_bug.cgi?id=1888486

Rob--W · 2024-03-28T23:29:51Z

@Rob--W Reading from your comment in the reading notes of Today's (2024-03-28) meeting:

This proposal doesn’t follow the new process. One of the aspects of the new process template is that there should be at least one browser committing to implementing the API.

It was under my impression there was general support for this feature across browsers and the next step would be a proposal.

Part of the proposal template includes an item about the "sponsoring" browser. As Devlin commented elsewhere in the PR, the purpose of that is to encourage proposals that reflect APIs that have a path towards realization rather than just being aspirational.

However I understand your concerns regarding ending up with many proposals without browsers moving forward to actually implement them. So I went ahead and created a patch for Firefox.
See: https://bugzilla.mozilla.org/show_bug.cgi?id=1888486

Thanks for the bug and patch!

proposals/i18n-getOSLanguage.md

Rob--W · 2024-03-30T23:57:28Z

proposals/i18n-getOSLanguage.md

+
+`i18n.getOSLanguage()` would synchronously return a [BCP47 language tag](https://www.w3.org/International/core/langtags/rfc3066bis.html) like `i18n.getUILanguage()` does right now.
+
+It would follow the following signature for [i18n.json](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/extensions/common/api/i18n.json):


When referencing source code, try to use a permalink where possible. In this case there has been a request to use IDL instead of JSON, so this line will probably end up being dropped. If not, here is the permalink: https://chromium.googlesource.com/chromium/src/+/4299ce68496b32ba309e2f012e0db5b4b8cd478a/extensions/common/api/i18n.json

Good to know! Updated the proposal to reflect this!

Rob--W · 2024-03-31T00:00:04Z

proposals/i18n-getOSLanguage.md

+
+**Summary**
+
+Allow to get the language of your operating system as an [BCP47 language tag](https://www.w3.org/International/core/langtags/rfc3066bis.html).


Given the discussion starting from #252 (comment), should we rename the proposal to i18n.getOSLanguages and let it return an array?

And also, guarantee the array to be non-empty?

hanguokai · 2024-03-31T00:57:54Z

As the discussion deepens (#252), I think there are four concepts here:

The Browser UI Language
The Browser Accept Languages
The OS UI Language
The OS Accept Languages

So, ideally there should be four functions:

i18n.getBrowserUILanguage()
i18n.getBrowserAcceptLanguages()
i18n.getOSUILanguage()
i18n.getOSAcceptLanguages()

And deprecate the current i18n.getUILanguage() and i18n.getAcceptLanguages().

Or using another design:

// return a single string for UI language
i18n.getUILanguage(
    prefer: "browser" // or "os"
);

// return an array for accept languages
i18n.getAcceptLanguages(
    prefer: "browser" // or "os"
);

proposals/i18n-getOSLanguage.md

carlosjeurissen · 2024-05-23T09:38:46Z

Updated the proposal which addresses the following:
i18n.getOSLanguage() has been renamed to i18n.getSystemUILanguage() to better indicate it is supposed to be the user interface of the operating system. Not the first preferred language specified in the operating system.

i18n.getPreferredSystemLanguages() has been added which returns the above mentioned preferred languages specified in the operating system. This aligns with the same API and name available in Electron apps.

For i18n.getPreferredSystemLanguages(), a patch for Firefox has been made, see: https://bugzilla.mozilla.org/show_bug.cgi?id=1888486

proposals/i18n-system-languages.md

aphillips · 2024-06-14T14:08:04Z

proposals/i18n-system-languages.md

+
+#### Use Cases
+
+Having the original system language(s) is useful for language-related extensions and for extensions who want to provide translations more true to the system language. For example, to adapt to a specific sub-language, like Belgium-Dutch (nl-BE). While i18n.getUILanguage would return 'nl'.


The example here is not very clear. There is a tendency to think that the primary language subtag (nl in the examples here) is "the language", but there are language variations that depend on additional subtags, such as script or region. For example, zh-Hans (Simplified Chinese) vs. zh-Hant (Traditional Chinese). Thus, the UI language is not guaranteed to be a single subtag.

It's also more useful/helpful to talk about the locale than it is to talk about the language, even if, for historical reasons, we use the word "Language" in the API names.

Note that locale means more than just language adaptation. Frequently, locale-based variations in number, date, time, measurement, etc. formatting constitute a key part of adaptation.

Note too that the use cases here are incomplete. The PR lists a number of different reasons, but you only have one in the document itself.

Thus:

Suggested change

Having the original system language(s) is useful for language-related extensions and for extensions who want to provide translations more true to the system language. For example, to adapt to a specific sub-language, like Belgium-Dutch (nl-BE). While i18n.getUILanguage would return 'nl'.

Extension authors might want to obtain the locale used by the user agent's host environment in order to format values (such as numbers, dates, and so forth) or do other locale-affected operations (such as list sorting) according to expectations of the user. For example, formatting the date `2024-06-15` varies between `en-US` (6/15/2024) and `en-GB` (15/6/2024), whereas `i18n.getUILanguage` might return only `en` (English).

Extension authors might want to obtain the locale used by the user agent's host environment to better match the runtime environment's localization. For example, the operating system might be running in `ff-NG` (Fulani as used in Nigeria), but the user agent might not be localized into this language and return `en` (English) for `i18n.getUILanguage`.

@aphillips Thanks so much for the suggestions! Applied the suggested change.

Also added a better example of the purest form use-case which describes i18n.getUILanguage returning a language tag with additional subtags which might not be sufficient for the user.

Lastly rewritten sentences to use locale instead of language where it makes sense based on your suggestion.

aphillips · 2024-06-14T14:10:02Z

proposals/i18n-system-languages.md

+
+### Schema
+
+`i18n.getPreferredSystemLanguages()` would asynchronously return a list of [BCP47 language tag](https://www.rfc-editor.org/bcp/bcp47.html) like `i18n.getAcceptLanguages()` does right now.


Probably you want to say that it returns an ordered list (BCP47 calls this a "language priority list").

Note that most operating systems don't provide a feature like this.

@aphillips thanks for noting and clarifying! Updated the sentence to reflect these suggestions. It is indeed meant to be an ordered list. As far as I know both mac and windows support this. But I could be wrong?

Co-authored-by: Addison Phillips <[email protected]>

xeenon · 2024-06-29T19:47:20Z

@carlosjeurissen There seems to have been a rebase issue, where this PR picked up a bunch of other changes from the repo outside of your proposal.

…stemUILanguage

Co-authored-by: Pavel Djundik <[email protected]>

Co-authored-by: Addison Phillips <[email protected]>

carlosjeurissen · 2024-06-30T06:09:45Z

@xeenon Thanks for noting! Has been addressed.

Co-authored-by: Simeon Vincent <[email protected]>

carlosjeurissen · 2024-09-24T19:02:26Z

Based on some of the feedback during TPAC, updated this PR and updated the Firefox patch.
See:
https://phabricator.services.mozilla.com/D206064
https://bugzilla.mozilla.org/show_bug.cgi?id=1888486

…cale tags

xeenon · 2024-10-02T16:22:03Z

proposals/i18n-system-languages.md

@@ -67,11 +70,14 @@ It would follow the following signature for [i18n.json](https://chromium.googles
  "name": "getSystemUILanguage",
  "type": "function",
  "nocompile": true,
-  "description": "Gets the current UI language of the Operating System. This is different from $(ref:i18n.getUILanguage) which returns the UI language of the web browser.",
+  "description": "Gets the current UI locale of the Operating System. This is different from $(ref:i18n.getUILanguage) which returns the UI locale of the web browser. This locale could include additional information like preferred datetime format and number system if supported by the OS.",


Is the "additional information" part a standard? I know Apple platforms can include it, but that isn't something we have had in web extensions before.

@xeenon yes, this is specified by unicode. This was discussed during the shared session with the WECG/I18NWG meeting at TPAC. However, giving a further look at this I see how this should not be part of the getSystemUILanguage. Updated the PR to reflect this. Still, providing this information can be useful, but it should be implemented using some other method / proposal.

https://bugs.webkit.org/show_bug.cgi?id=280586 Reviewed by NOBODY (OOPS!). WECG issue: w3c/webextensions#252 WECG proposal: w3c/webextensions#569 Also changed the i18n APIs to return `"und"` instead of `undefined` when there is no language code. * Source/WebKit/Platform/spi/Cocoa/FoundationSPI.h: * Source/WebKit/Shared/Extensions/WebExtensionUtilities.mm: (WebKit::toWebAPI): Return "und" where then is no language code. * Source/WebKit/WebProcess/Extensions/API/Cocoa/WebExtensionAPILocalizationCocoa.mm: (WebKit::WebExtensionAPILocalization::getPreferredSystemLanguages): (WebKit::WebExtensionAPILocalization::getSystemUILanguage): * Source/WebKit/WebProcess/Extensions/API/WebExtensionAPILocalization.h: * Source/WebKit/WebProcess/Extensions/Interfaces/WebExtensionAPILocalization.idl: * Tools/TestWebKitAPI/Tests/WebKitCocoa/WKWebExtensionAPILocalization.mm: (TestWebKitAPI::localeStringInWebExtensionFormat): Return "und". (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18n)): (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18nWithFallback)): (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18nWithoutMessages)): (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18nWithoutDefaultLocale)):

https://bugs.webkit.org/show_bug.cgi?id=280586 Reviewed by Brian Weinstein. WECG issue: w3c/webextensions#252 WECG proposal: w3c/webextensions#569 Also changed the i18n APIs to return `"und"` instead of `undefined` when there is no language code. * Source/WebKit/Platform/spi/Cocoa/FoundationSPI.h: * Source/WebKit/Shared/Extensions/WebExtensionUtilities.mm: (WebKit::toWebAPI): Return "und" where then is no language code. * Source/WebKit/WebProcess/Extensions/API/Cocoa/WebExtensionAPILocalizationCocoa.mm: (WebKit::WebExtensionAPILocalization::getPreferredSystemLanguages): (WebKit::WebExtensionAPILocalization::getSystemUILanguage): * Source/WebKit/WebProcess/Extensions/API/WebExtensionAPILocalization.h: * Source/WebKit/WebProcess/Extensions/Interfaces/WebExtensionAPILocalization.idl: * Tools/TestWebKitAPI/Tests/WebKitCocoa/WKWebExtensionAPILocalization.mm: (TestWebKitAPI::localeStringInWebExtensionFormat): Return "und". (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18n)): (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18nWithFallback)): (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18nWithoutMessages)): (TestWebKitAPI::TEST(WKWebExtensionAPILocalization, i18nWithoutDefaultLocale)): Canonical link: https://commits.webkit.org/284637@main

xeenon approved these changes Mar 19, 2024

View reviewed changes

xeenon mentioned this pull request Mar 28, 2024

Agenda discussion for public meeting on 2024-03-28 #567

Closed

xeenon requested review from Rob--W and rdcronin March 28, 2024 15:33

rdcronin suggested changes Mar 28, 2024

View reviewed changes

Rob--W mentioned this pull request Mar 28, 2024

Publish minutes of 2024-03-28 meeting #578

Merged

carlosjeurissen added topic: localization i18n-tracker Group bringing to attention of Internationalization, or tracked by i18n but not needing response. labels Mar 28, 2024

w3cbot mentioned this pull request Mar 29, 2024

Add getOSLanguage proposal w3c/i18n-activity#1844

Open

carlosjeurissen mentioned this pull request Mar 29, 2024

Introducing browser.i18n.getOSLanguage #252

Open

aphillips reviewed Mar 30, 2024

View reviewed changes

proposals/i18n-getOSLanguage.md Outdated Show resolved Hide resolved

Rob--W reviewed Mar 31, 2024

View reviewed changes

aphillips reviewed Apr 18, 2024

View reviewed changes

proposals/i18n-getOSLanguage.md Outdated Show resolved Hide resolved

bershanskiy mentioned this pull request Apr 23, 2024

Agenda discussion for public meeting on 2024-04-25 #590

Closed

Rob--W mentioned this pull request Apr 25, 2024

Publish minutes of 2024-04-25 meeting #602

Merged

xeenon mentioned this pull request May 22, 2024

Agenda discussion for public meeting on 2024-05-23 #609

Closed

carlosjeurissen changed the title ~~Add getOSLanguage proposal~~ Add i18n-system-languages proposal May 23, 2024

Rob--W mentioned this pull request May 23, 2024

Publish minutes of 2024-05-23 meeting #620

Merged

Rob--W self-requested a review May 23, 2024 16:32

carlosjeurissen requested review from rdcronin and aphillips May 29, 2024 19:33

Rob--W mentioned this pull request Jun 6, 2024

Publish minutes of 2024-06-06 meeting #634

Merged

xPaw reviewed Jun 14, 2024

View reviewed changes

proposals/i18n-system-languages.md Outdated Show resolved Hide resolved

carlosjeurissen mentioned this pull request Jun 14, 2024

Per-extension language preferences #258

Open

aphillips reviewed Jun 14, 2024

View reviewed changes

carlosjeurissen changed the title ~~Add i18n-system-languages proposal~~ Proposal: i18n-system-languages Jun 19, 2024

carlosjeurissen and others added 4 commits June 25, 2024 15:27

Rename IETF tags to BCP47 language tags

1bf297c

Remove > from title

b9ab150

Replace chromium source reference with a permalink

da34a81

Update proposals/i18n-getOSLanguage.md

6107700

Co-authored-by: Addison Phillips <[email protected]>

carlosjeurissen force-pushed the getOSLanguage-proposal branch from b4ce1eb to 84248c4 Compare June 25, 2024 13:27

carlosjeurissen and others added 8 commits June 30, 2024 08:08

Update proposal to include both getPreferredSystemLanguages and getSy…

38e9f39

…stemUILanguage

Rename proposal file to better reflect the proposal

4eb3df1

Fix proposal title

280efb5

Update proposals/i18n-system-languages.md

90dec9b

Co-authored-by: Pavel Djundik <[email protected]>

Update proposals/i18n-system-languages.md

1d995e9

Co-authored-by: Addison Phillips <[email protected]>

Clarify the type of list returned by getPreferredSystemLanguages

89f08b3

Rewrite sentences to use locale instead of language when it makes sense

76acf81

Add purest form use-case

395c02e

carlosjeurissen force-pushed the getOSLanguage-proposal branch from 84248c4 to 395c02e Compare June 30, 2024 06:08

carlosjeurissen and others added 4 commits September 23, 2024 20:17

Update proposals/i18n-system-languages.md

07b64c9

Co-authored-by: Simeon Vincent <[email protected]>

Clarify additional subtags on getSystemUILanguage

e8ae3a9

Update getSystemUILanguage to be async

7e3c88f

Clarify getPreferredSystemLanguages callback parameter

64b942d

Rob--W mentioned this pull request Sep 29, 2024

Publish minutes of 2024-09-23 - 2024-09-27 TPAC meetings #704

Merged

Clarify getPreferredSystemLanguages would not insert less specific lo…

42f71ae

…cale tags

xeenon reviewed Oct 2, 2024

View reviewed changes

xeenon mentioned this pull request Oct 3, 2024

Implement i18n.getSystemUILanguage and i18n.getPreferredSystemLanguages. WebKit/WebKit#34645

Merged

Remove additional subtags note on getSystemUILanguage

7ac0a42

xeenon mentioned this pull request Oct 10, 2024

Agenda discussion for public meeting on 2024-10-10 #697

Closed

dotproto mentioned this pull request Oct 16, 2024

Publish minutes of 2024-10-10 meeting #710

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposal: i18n-system-languages #569

Proposal: i18n-system-languages #569

carlosjeurissen commented Mar 18, 2024 •

edited

Loading

rdcronin left a comment

rdcronin Mar 28, 2024

xeenon Mar 28, 2024

rdcronin Mar 28, 2024

carlosjeurissen Mar 28, 2024 •

edited

Loading

rdcronin Mar 28, 2024

carlosjeurissen Mar 28, 2024

xeenon Mar 28, 2024

carlosjeurissen commented Mar 28, 2024

Rob--W commented Mar 28, 2024

Rob--W Mar 30, 2024

carlosjeurissen Mar 31, 2024

Rob--W Mar 31, 2024

hanguokai commented Mar 31, 2024 •

edited

Loading

carlosjeurissen commented May 23, 2024 •

edited

Loading

aphillips Jun 14, 2024

carlosjeurissen Jun 14, 2024

aphillips Jun 14, 2024

carlosjeurissen Jun 14, 2024

xeenon commented Jun 29, 2024

carlosjeurissen commented Jun 30, 2024

carlosjeurissen commented Sep 24, 2024

xeenon Oct 2, 2024

carlosjeurissen Oct 4, 2024


		`i18n.getOSLanguage()` would synchronously return a [BCP47 language tag](https://www.w3.org/International/core/langtags/rfc3066bis.html) like `i18n.getUILanguage()` does right now.

		It would follow the following signature for [i18n.json](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/extensions/common/api/i18n.json):


		Summary

		Allow to get the language of your operating system as an [BCP47 language tag](https://www.w3.org/International/core/langtags/rfc3066bis.html).


		#### Use Cases

		Having the original system language(s) is useful for language-related extensions and for extensions who want to provide translations more true to the system language. For example, to adapt to a specific sub-language, like Belgium-Dutch (nl-BE). While i18n.getUILanguage would return 'nl'.

-Having the original system language(s) is useful for language-related extensions and for extensions who want to provide translations more true to the system language. For example, to adapt to a specific sub-language, like Belgium-Dutch (nl-BE). While i18n.getUILanguage would return 'nl'.
+Extension authors might want to obtain the locale used by the user agent's host environment in order to format values (such as numbers, dates, and so forth) or do other locale-affected operations (such as list sorting) according to expectations of the user. For example, formatting the date `2024-06-15` varies between `en-US` (6/15/2024) and `en-GB` (15/6/2024), whereas `i18n.getUILanguage` might return only `en` (English).
+Extension authors might want to obtain the locale used by the user agent's host environment to better match the runtime environment's localization. For example, the operating system might be running in `ff-NG` (Fulani as used in Nigeria), but the user agent might not be localized into this language and return `en` (English) for `i18n.getUILanguage`.


		### Schema

		`i18n.getPreferredSystemLanguages()` would asynchronously return a list of [BCP47 language tag](https://www.rfc-editor.org/bcp/bcp47.html) like `i18n.getAcceptLanguages()` does right now.

		Document Metadata

		Author: carlosjeurissen

Proposal: i18n-system-languages #569

Are you sure you want to change the base?

Proposal: i18n-system-languages #569

Conversation

carlosjeurissen commented Mar 18, 2024 • edited Loading

rdcronin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlosjeurissen Mar 28, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlosjeurissen commented Mar 28, 2024

Rob--W commented Mar 28, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hanguokai commented Mar 31, 2024 • edited Loading

carlosjeurissen commented May 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xeenon commented Jun 29, 2024

carlosjeurissen commented Jun 30, 2024

carlosjeurissen commented Sep 24, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlosjeurissen commented Mar 18, 2024 •

edited

Loading

carlosjeurissen Mar 28, 2024 •

edited

Loading

hanguokai commented Mar 31, 2024 •

edited

Loading

carlosjeurissen commented May 23, 2024 •

edited

Loading