From a1ccb489667fb2d07ab3f52deb26002502f01ff5 Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:06 +0000
Subject: [PATCH 01/12] feat: add app.getSystemLanguage() API

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 docs/api/app.md                       |  8 +++++++-
 shell/browser/api/electron_api_app.cc | 11 +++++++++++
 shell/browser/api/electron_api_app.h  |  1 +
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index 202ce053e4d4a..e8fb5f69c86fa 100755
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -725,10 +725,16 @@ Returns `string` - User operating system's locale two-letter [ISO 3166](https://
 
 ### `app.getSystemLocale()`
 
-Returns `string` - The current system locale. On Windows and Linux, it is fetched using Chromium's `i18n` library. On macOS, the `NSLocale` object is used instead.
+Returns `string` - The current system locale. On Windows and Linux, it is fetched using Chromium's `i18n` library. On macOS, `[NSLocale currentLocale]` is used instead.
+
+Note that the system locale is not necessarily the preferred system language. For example, The system locale on Windows 11 returns the locale used for the region. On macOS Monterey, it returns a string containing a mix of the language and the region. For example, setting the most preferred language to Brazilian Portuguese but setting the region to Finland returns `pt-FI` instead of `pt-BR`.
 
 **Note:** This API must be called after the `ready` event is emitted.
 
+### `app.getSystemLanguage()`
+
+Returns `string` - The user's most preferred system language, including the country code if applicable. If no preferred system languages are found, returns an empty string.
+
 ### `app.addRecentDocument(path)` _macOS_ _Windows_
 
 * `path` string
diff --git a/shell/browser/api/electron_api_app.cc b/shell/browser/api/electron_api_app.cc
index 2ba1e0adbe872..75b9959b7aa4d 100644
--- a/shell/browser/api/electron_api_app.cc
+++ b/shell/browser/api/electron_api_app.cc
@@ -66,6 +66,7 @@
 #include "shell/common/gin_converters/value_converter.h"
 #include "shell/common/gin_helper/dictionary.h"
 #include "shell/common/gin_helper/object_template_builder.h"
+#include "shell/common/language_util.h"
 #include "shell/common/node_includes.h"
 #include "shell/common/options_switches.h"
 #include "shell/common/platform_util.h"
@@ -1040,6 +1041,15 @@ std::string App::GetLocale() {
   return g_browser_process->GetApplicationLocale();
 }
 
+std::string App::GetSystemLanguage() const {
+  std::vector<std::string> preferred_languages = GetPreferredLanguages();
+  if (preferred_languages.size()) {
+    return preferred_languages[0];
+  } else {
+    return std::string();
+  }
+}
+
 std::string App::GetSystemLocale(gin_helper::ErrorThrower thrower) const {
   if (!Browser::Get()->is_ready()) {
     thrower.ThrowError(
@@ -1796,6 +1806,7 @@ gin::ObjectTemplateBuilder App::GetObjectTemplateBuilder(v8::Isolate* isolate) {
       .SetMethod("setAppLogsPath", &App::SetAppLogsPath)
       .SetMethod("setDesktopName", &App::SetDesktopName)
       .SetMethod("getLocale", &App::GetLocale)
+      .SetMethod("getSystemLanguage", &App::GetSystemLanguage)
       .SetMethod("getSystemLocale", &App::GetSystemLocale)
       .SetMethod("getLocaleCountryCode", &App::GetLocaleCountryCode)
 #if BUILDFLAG(USE_NSS_CERTS)
diff --git a/shell/browser/api/electron_api_app.h b/shell/browser/api/electron_api_app.h
index 40f76b19148b1..717c1c7c34d83 100644
--- a/shell/browser/api/electron_api_app.h
+++ b/shell/browser/api/electron_api_app.h
@@ -191,6 +191,7 @@ class App : public ElectronBrowserClient::Delegate,
   void SetDesktopName(const std::string& desktop_name);
   std::string GetLocale();
   std::string GetLocaleCountryCode();
+  std::string GetSystemLanguage() const;
   std::string GetSystemLocale(gin_helper::ErrorThrower thrower) const;
   void OnSecondInstance(const base::CommandLine& cmd,
                         const base::FilePath& cwd,

From 47b1405798230a0024c25dfd1f12a627efc5ec8e Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:11 +0000
Subject: [PATCH 02/12] Change the API to getPreferredSystemLanguages

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 docs/api/app.md                        |  4 ++--
 shell/browser/api/electron_api_app.cc  | 12 ++++--------
 shell/browser/api/electron_api_app.h   |  2 +-
 spec/api-app-spec.ts                   |  6 ++++++
 spec/chromium-spec.ts                  |  7 ++++---
 spec/fixtures/api/locale-check/main.js |  2 +-
 6 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index e8fb5f69c86fa..e6aab39c02588 100755
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -731,9 +731,9 @@ Note that the system locale is not necessarily the preferred system language. Fo
 
 **Note:** This API must be called after the `ready` event is emitted.
 
-### `app.getSystemLanguage()`
+### `app.getPreferredSystemLanguages()`
 
-Returns `string` - The user's most preferred system language, including the country code if applicable. If no preferred system languages are found, returns an empty string.
+Returns `string[]` - The user's preferred system languages, including the country codes if applicable.
 
 ### `app.addRecentDocument(path)` _macOS_ _Windows_
 
diff --git a/shell/browser/api/electron_api_app.cc b/shell/browser/api/electron_api_app.cc
index 75b9959b7aa4d..dcb231c600218 100644
--- a/shell/browser/api/electron_api_app.cc
+++ b/shell/browser/api/electron_api_app.cc
@@ -1041,13 +1041,8 @@ std::string App::GetLocale() {
   return g_browser_process->GetApplicationLocale();
 }
 
-std::string App::GetSystemLanguage() const {
-  std::vector<std::string> preferred_languages = GetPreferredLanguages();
-  if (preferred_languages.size()) {
-    return preferred_languages[0];
-  } else {
-    return std::string();
-  }
+std::vector<std::string> App::GetPreferredSystemLanguages() const {
+  return GetPreferredLanguages();
 }
 
 std::string App::GetSystemLocale(gin_helper::ErrorThrower thrower) const {
@@ -1806,7 +1801,8 @@ gin::ObjectTemplateBuilder App::GetObjectTemplateBuilder(v8::Isolate* isolate) {
       .SetMethod("setAppLogsPath", &App::SetAppLogsPath)
       .SetMethod("setDesktopName", &App::SetDesktopName)
       .SetMethod("getLocale", &App::GetLocale)
-      .SetMethod("getSystemLanguage", &App::GetSystemLanguage)
+      .SetMethod("getPreferredSystemLanguages",
+                 &App::GetPreferredSystemLanguages)
       .SetMethod("getSystemLocale", &App::GetSystemLocale)
       .SetMethod("getLocaleCountryCode", &App::GetLocaleCountryCode)
 #if BUILDFLAG(USE_NSS_CERTS)
diff --git a/shell/browser/api/electron_api_app.h b/shell/browser/api/electron_api_app.h
index 717c1c7c34d83..eaa7e9f0afb29 100644
--- a/shell/browser/api/electron_api_app.h
+++ b/shell/browser/api/electron_api_app.h
@@ -191,7 +191,7 @@ class App : public ElectronBrowserClient::Delegate,
   void SetDesktopName(const std::string& desktop_name);
   std::string GetLocale();
   std::string GetLocaleCountryCode();
-  std::string GetSystemLanguage() const;
+  std::vector<std::string> GetPreferredSystemLanguages() const;
   std::string GetSystemLocale(gin_helper::ErrorThrower thrower) const;
   void OnSecondInstance(const base::CommandLine& cmd,
                         const base::FilePath& cwd,
diff --git a/spec/api-app-spec.ts b/spec/api-app-spec.ts
index 60f51fbe1b92e..951cb723b4e01 100644
--- a/spec/api-app-spec.ts
+++ b/spec/api-app-spec.ts
@@ -124,6 +124,12 @@ describe('app module', () => {
     });
   });
 
+  describe('app.getPreferredSystemLanguages()', () => {
+    it('should not be empty', () => {
+      expect(app.getPreferredSystemLanguages().length).to.not.equal(0);
+    });
+  });
+
   describe('app.getLocaleCountryCode()', () => {
     it('should be empty or have length of two', () => {
       const localeCountryCode = app.getLocaleCountryCode();
diff --git a/spec/chromium-spec.ts b/spec/chromium-spec.ts
index d12d2be4ec130..5200e92e7966d 100644
--- a/spec/chromium-spec.ts
+++ b/spec/chromium-spec.ts
@@ -375,6 +375,7 @@ describe('command line switches', () => {
   describe('--lang switch', () => {
     const currentLocale = app.getLocale();
     const currentSystemLocale = app.getSystemLocale();
+    const currentPreferredLanguages = JSON.stringify(app.getPreferredSystemLanguages());
     const testLocale = async (locale: string, result: string, printEnv: boolean = false) => {
       const appPath = path.join(fixturesPath, 'api', 'locale-check');
       const args = [appPath, `--set-lang=${locale}`];
@@ -397,9 +398,9 @@ describe('command line switches', () => {
       expect(output).to.equal(result);
     };
 
-    it('should set the locale', async () => testLocale('fr', `fr|${currentSystemLocale}`));
-    it('should set the locale with country code', async () => testLocale('zh-CN', `zh-CN|${currentSystemLocale}`));
-    it('should not set an invalid locale', async () => testLocale('asdfkl', `${currentLocale}|${currentSystemLocale}`));
+    it('should set the locale', async () => testLocale('fr', `fr|${currentSystemLocale}|${currentPreferredLanguages}`));
+    it('should set the locale with country code', async () => testLocale('zh-CN', `zh-CN|${currentSystemLocale}|${currentPreferredLanguages}`));
+    it('should not set an invalid locale', async () => testLocale('asdfkl', `${currentLocale}|${currentSystemLocale}|${currentPreferredLanguages}`));
 
     const lcAll = String(process.env.LC_ALL);
     ifit(process.platform === 'linux')('current process has a valid LC_ALL env', async () => {
diff --git a/spec/fixtures/api/locale-check/main.js b/spec/fixtures/api/locale-check/main.js
index dd4e6317dbb61..69bbdd583c0e9 100644
--- a/spec/fixtures/api/locale-check/main.js
+++ b/spec/fixtures/api/locale-check/main.js
@@ -9,7 +9,7 @@ app.whenReady().then(() => {
   if (process.argv[3] === '--print-env') {
     process.stdout.write(String(process.env.LC_ALL));
   } else {
-    process.stdout.write(`${app.getLocale()}|${app.getSystemLocale()}`);
+    process.stdout.write(`${app.getLocale()}|${app.getSystemLocale()}|${JSON.stringify(app.getPreferredSystemLanguages())}`);
   }
   process.stdout.end();
 

From b2d2b702cd3703e3edb53a60a2e2a993276e447a Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:14 +0000
Subject: [PATCH 03/12] Fix test

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 spec/api-app-spec.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/spec/api-app-spec.ts b/spec/api-app-spec.ts
index 951cb723b4e01..d18e30f9c715d 100644
--- a/spec/api-app-spec.ts
+++ b/spec/api-app-spec.ts
@@ -125,9 +125,13 @@ describe('app module', () => {
   });
 
   describe('app.getPreferredSystemLanguages()', () => {
-    it('should not be empty', () => {
+    ifit(process.platform !== 'linux')('should not be empty', () => {
       expect(app.getPreferredSystemLanguages().length).to.not.equal(0);
     });
+
+    ifit(process.platform === 'linux')('should be empty', () => {
+      expect(app.getPreferredSystemLanguages().length).to.equal(0);
+    });
   });
 
   describe('app.getLocaleCountryCode()', () => {

From ce4456a1754a6e1b88138b8cf79a9ff09e4a05cf Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:17 +0000
Subject: [PATCH 04/12] Clarify docs and add Linux impl

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 docs/api/app.md                     | 17 ++++++++++++++---
 shell/common/language_util_linux.cc | 28 ++++++++++++++++++++++++----
 spec/api-app-spec.ts                |  7 +++++--
 3 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index e6aab39c02588..5019ac6633623 100755
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -725,15 +725,26 @@ Returns `string` - User operating system's locale two-letter [ISO 3166](https://
 
 ### `app.getSystemLocale()`
 
-Returns `string` - The current system locale. On Windows and Linux, it is fetched using Chromium's `i18n` library. On macOS, `[NSLocale currentLocale]` is used instead.
+Returns `string` - The current system locale. On Windows and Linux, it is fetched using Chromium's `i18n` library. On macOS, `[NSLocale currentLocale]` is used instead. To get the user's current system language, which is not always the same as the locale, it is better to use `app.getPreferredSystemLanguages()` and take the first result.
 
-Note that the system locale is not necessarily the preferred system language. For example, The system locale on Windows 11 returns the locale used for the region. On macOS Monterey, it returns a string containing a mix of the language and the region. For example, setting the most preferred language to Brazilian Portuguese but setting the region to Finland returns `pt-FI` instead of `pt-BR`.
+Note that the system locale is not always the most preferred system language:
+
+* On Windows 11, the locale returned is the one used for the regional format. For example, if the regional format is `zh-CN` and the most preferred system language is `fr-FR`, then `zh-CN` is returned.
+* On macOS Monterey, the locale is a string containing a mix of the most preferred system language and the region. For example, if the most preferred language is `pt-BR` but the region is Finland, the locale is `pt-FI` instead of `pt-BR`.
+
+Different operating systems also use the regional data differently:
+
+* Windows 11 uses the regional format to render dates and times.
+* macOS Monterey uses the region for formatting numbers, selecting the currency symbol to use, and rendering dates and times.
 
 **Note:** This API must be called after the `ready` event is emitted.
 
 ### `app.getPreferredSystemLanguages()`
 
-Returns `string[]` - The user's preferred system languages, including the country codes if applicable.
+Returns `string[]` - The user's preferred system languages from most preferred to least preferred, including the country codes if applicable. A user can modify and add to this list on Windows or macOS through the Language and Region settings.
+Some languages returned by this API appear in a different format than locales returned by `app.getLocale()`. For example, on Windows and macOS, the language code for Simplified Chinese starts with `zh-Hans`, and the language code for Traditional Chinese starts with `zh-Hant`.
+To get the user's system locale or region, which is not always the same as their preferred system languages, one can use `app.getSystemLocale()`.
+On Linux, if `USE_GLIB` is defined, there will always be at least the entry `C`.
 
 ### `app.addRecentDocument(path)` _macOS_ _Windows_
 
diff --git a/shell/common/language_util_linux.cc b/shell/common/language_util_linux.cc
index 76bc557741ba0..e0ad24a0001cc 100644
--- a/shell/common/language_util_linux.cc
+++ b/shell/common/language_util_linux.cc
@@ -4,14 +4,34 @@
 
 #include "shell/common/language_util.h"
 
-#include "ui/base/l10n/l10n_util.h"
+#include "base/i18n/rtl.h"
+
+#if defined(USE_GLIB)
+#include <glib.h>
+#endif
 
 namespace electron {
 
 std::vector<std::string> GetPreferredLanguages() {
-  // Return empty as there's no API to use. You may be able to use
-  // GetApplicationLocale() of a browser process.
-  return std::vector<std::string>{};
+  std::vector<std::string> preferredLanguages;
+
+#if defined(USE_GLIB)
+  // From
+  // https://source.chromium.org/chromium/chromium/src/+/refs/tags/108.0.5329.0:ui/base/l10n/l10n_util.cc;l=543-554
+  // GLib implements correct environment variable parsing with
+  // the precedence order: LANGUAGE, LC_ALL, LC_MESSAGES and LANG.
+  const char* const* languages = g_get_language_names();
+  DCHECK(languages);   // A valid pointer is guaranteed.
+  DCHECK(*languages);  // At least one entry, "C", is guaranteed.
+
+  for (; *languages; ++languages) {
+    preferredLanguages.push_back(base::i18n::GetCanonicalLocale(*languages));
+  }
+#endif
+
+  // If USE_GLIB isn't defined, an empty vector is returned.
+  // You may be able to use GetApplicationLocale() of a browser process instead.
+  return preferredLanguages;
 }
 
 }  // namespace electron
diff --git a/spec/api-app-spec.ts b/spec/api-app-spec.ts
index d18e30f9c715d..c608396bdf151 100644
--- a/spec/api-app-spec.ts
+++ b/spec/api-app-spec.ts
@@ -129,8 +129,11 @@ describe('app module', () => {
       expect(app.getPreferredSystemLanguages().length).to.not.equal(0);
     });
 
-    ifit(process.platform === 'linux')('should be empty', () => {
-      expect(app.getPreferredSystemLanguages().length).to.equal(0);
+    ifit(process.platform === 'linux')('should be empty or contain C entry', () => {
+      const languages = app.getPreferredSystemLanguages();
+      if (languages.length) {
+        expect(languages).to.include('C');
+      }
     });
   });
 

From 74505bb3050e8176ab5494554433ff1269ef7e91 Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:23 +0000
Subject: [PATCH 05/12] Remove USE_GLIB

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 shell/common/language_util_linux.cc | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/shell/common/language_util_linux.cc b/shell/common/language_util_linux.cc
index e0ad24a0001cc..6296d83ed10a0 100644
--- a/shell/common/language_util_linux.cc
+++ b/shell/common/language_util_linux.cc
@@ -6,16 +6,13 @@
 
 #include "base/i18n/rtl.h"
 
-#if defined(USE_GLIB)
 #include <glib.h>
-#endif
 
 namespace electron {
 
 std::vector<std::string> GetPreferredLanguages() {
   std::vector<std::string> preferredLanguages;
 
-#if defined(USE_GLIB)
   // From
   // https://source.chromium.org/chromium/chromium/src/+/refs/tags/108.0.5329.0:ui/base/l10n/l10n_util.cc;l=543-554
   // GLib implements correct environment variable parsing with
@@ -27,10 +24,7 @@ std::vector<std::string> GetPreferredLanguages() {
   for (; *languages; ++languages) {
     preferredLanguages.push_back(base::i18n::GetCanonicalLocale(*languages));
   }
-#endif
 
-  // If USE_GLIB isn't defined, an empty vector is returned.
-  // You may be able to use GetApplicationLocale() of a browser process instead.
   return preferredLanguages;
 }
 

From 6203b259160b8083dd2a21c8f064e6c5e7015604 Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:28 +0000
Subject: [PATCH 06/12] Don't add C to list

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 shell/common/language_util_linux.cc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/shell/common/language_util_linux.cc b/shell/common/language_util_linux.cc
index 6296d83ed10a0..57bd134b92554 100644
--- a/shell/common/language_util_linux.cc
+++ b/shell/common/language_util_linux.cc
@@ -13,7 +13,7 @@ namespace electron {
 std::vector<std::string> GetPreferredLanguages() {
   std::vector<std::string> preferredLanguages;
 
-  // From
+  // Based on
   // https://source.chromium.org/chromium/chromium/src/+/refs/tags/108.0.5329.0:ui/base/l10n/l10n_util.cc;l=543-554
   // GLib implements correct environment variable parsing with
   // the precedence order: LANGUAGE, LC_ALL, LC_MESSAGES and LANG.
@@ -22,7 +22,9 @@ std::vector<std::string> GetPreferredLanguages() {
   DCHECK(*languages);  // At least one entry, "C", is guaranteed.
 
   for (; *languages; ++languages) {
-    preferredLanguages.push_back(base::i18n::GetCanonicalLocale(*languages));
+    if (strcmp(*languages, "C") != 0) {
+      preferredLanguages.push_back(base::i18n::GetCanonicalLocale(*languages));
+    }
   }
 
   return preferredLanguages;

From ed244bb8c37f3dcb35023ff0e73602a96542cd61 Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:37 +0000
Subject: [PATCH 07/12] Remove examples since there's a lot of edge cases

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 docs/api/app.md | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index 5019ac6633623..90a50adf9a611 100755
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -725,26 +725,22 @@ Returns `string` - User operating system's locale two-letter [ISO 3166](https://
 
 ### `app.getSystemLocale()`
 
-Returns `string` - The current system locale. On Windows and Linux, it is fetched using Chromium's `i18n` library. On macOS, `[NSLocale currentLocale]` is used instead. To get the user's current system language, which is not always the same as the locale, it is better to use `app.getPreferredSystemLanguages()` and take the first result.
-
-Note that the system locale is not always the most preferred system language:
-
-* On Windows 11, the locale returned is the one used for the regional format. For example, if the regional format is `zh-CN` and the most preferred system language is `fr-FR`, then `zh-CN` is returned.
-* On macOS Monterey, the locale is a string containing a mix of the most preferred system language and the region. For example, if the most preferred language is `pt-BR` but the region is Finland, the locale is `pt-FI` instead of `pt-BR`.
+Returns `string` - The current system locale. On Windows and Linux, it is fetched using Chromium's `i18n` library. On macOS, `[NSLocale currentLocale]` is used instead. To get the user's current system language, which is not always the same as the locale, it is better to use [`app.getPreferredSystemLanguages()`](#appgetpreferredsystemlanguages).
 
 Different operating systems also use the regional data differently:
 
-* Windows 11 uses the regional format to render dates and times.
-* macOS Monterey uses the region for formatting numbers, selecting the currency symbol to use, and rendering dates and times.
+* Windows 11 uses the regional format for numbers, dates, and times.
+* macOS Monterey uses the region for formatting numbers, dates, times, and for selecting the currency symbol to use.
+
+Therefore, this API can be used for purposes such as choosing a format for rendering dates and times in a calendar app, especially when the developer wants the format to be consistent with the OS.
 
 **Note:** This API must be called after the `ready` event is emitted.
 
 ### `app.getPreferredSystemLanguages()`
 
 Returns `string[]` - The user's preferred system languages from most preferred to least preferred, including the country codes if applicable. A user can modify and add to this list on Windows or macOS through the Language and Region settings.
-Some languages returned by this API appear in a different format than locales returned by `app.getLocale()`. For example, on Windows and macOS, the language code for Simplified Chinese starts with `zh-Hans`, and the language code for Traditional Chinese starts with `zh-Hant`.
-To get the user's system locale or region, which is not always the same as their preferred system languages, one can use `app.getSystemLocale()`.
-On Linux, if `USE_GLIB` is defined, there will always be at least the entry `C`.
+
+This API can be used for purposes such as deciding what language to present the application in.
 
 ### `app.addRecentDocument(path)` _macOS_ _Windows_
 

From 263aea0327b1c311b32b6004f7805c1ef36c153f Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:39 +0000
Subject: [PATCH 08/12] Fix lint

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 shell/common/language_util_linux.cc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/shell/common/language_util_linux.cc b/shell/common/language_util_linux.cc
index 57bd134b92554..1f4dd357784b1 100644
--- a/shell/common/language_util_linux.cc
+++ b/shell/common/language_util_linux.cc
@@ -4,10 +4,10 @@
 
 #include "shell/common/language_util.h"
 
-#include "base/i18n/rtl.h"
-
 #include <glib.h>
 
+#include "base/i18n/rtl.h"
+
 namespace electron {
 
 std::vector<std::string> GetPreferredLanguages() {

From b60f83ddb8991b81155a324087b76e1e0e63ddaf Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:41 +0000
Subject: [PATCH 09/12] Add examples

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 docs/api/app.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/api/app.md b/docs/api/app.md
index 90a50adf9a611..f364d8f12ca97 100755
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -717,6 +717,8 @@ To set the locale, you'll want to use a command line switch at app startup, whic
 
 **Note:** This API must be called after the `ready` event is emitted.
 
+**Note:** To see example return values of this API compared to other locale and language APIs, see [`app.getPreferredSystemLanguages()`](#appgetpreferredsystemlanguages).
+
 ### `app.getLocaleCountryCode()`
 
 Returns `string` - User operating system's locale two-letter [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. The value is taken from native OS APIs.
@@ -736,12 +738,27 @@ Therefore, this API can be used for purposes such as choosing a format for rende
 
 **Note:** This API must be called after the `ready` event is emitted.
 
+**Note:** To see example return values of this API compared to other locale and language APIs, see [`app.getPreferredSystemLanguages()`](#appgetpreferredsystemlanguages).
+
 ### `app.getPreferredSystemLanguages()`
 
 Returns `string[]` - The user's preferred system languages from most preferred to least preferred, including the country codes if applicable. A user can modify and add to this list on Windows or macOS through the Language and Region settings.
 
 This API can be used for purposes such as deciding what language to present the application in.
 
+Here are some examples of return values of the various language and locale APIs with different configurations:
+
+* For Windows, where the application locale is French, the region is Simplified Chinese (China), and the preferred system languages from most to least preferred are French (Canada), English (US), and Simplified Chinese (China):
+  * `app.getLocale()` returns `'fr'`
+  * `app.getSystemLocale()` returns `'zh-CN'`
+  * `app.getPreferredSystemLanguages()` returns `['fr-CA', 'en-US', 'zh-Hans-CN']`
+* On macOS, where the application locale is German, the region is Finland, and the preferred system languages from most to least preferred are French, French (Canada), Simplified Chinese, and Spanish (Latin America):
+  * `app.getLocale()` returns `'de'`
+  * `app.getSystemLocale()` returns `'fr-FI'`
+  * `app.getPreferredSystemLanguages()` returns `['fr-FI', 'fr-CA', 'zh-Hans-FI', 'es-419']`
+
+Both the available languages and regions and the possible return values differ between the two operating systems.
+
 ### `app.addRecentDocument(path)` _macOS_ _Windows_
 
 * `path` string

From 7315a3e48e2eec513924437e509c2094ed461607 Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:44 +0000
Subject: [PATCH 10/12] Fix compile error

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 shell/common/language_util_linux.cc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/shell/common/language_util_linux.cc b/shell/common/language_util_linux.cc
index 1f4dd357784b1..58754f80ef825 100644
--- a/shell/common/language_util_linux.cc
+++ b/shell/common/language_util_linux.cc
@@ -6,6 +6,7 @@
 
 #include <glib.h>
 
+#include "base/check.h"
 #include "base/i18n/rtl.h"
 
 namespace electron {

From 588b37c4635ac9936db673bf964e805c6d6de173 Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:45 +0000
Subject: [PATCH 11/12] Apply PR feedback

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 shell/browser/api/electron_api_app.cc | 7 +------
 shell/browser/api/electron_api_app.h  | 1 -
 spec/api-app-spec.ts                  | 2 +-
 3 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/shell/browser/api/electron_api_app.cc b/shell/browser/api/electron_api_app.cc
index dcb231c600218..bcbd4230ebc13 100644
--- a/shell/browser/api/electron_api_app.cc
+++ b/shell/browser/api/electron_api_app.cc
@@ -1041,10 +1041,6 @@ std::string App::GetLocale() {
   return g_browser_process->GetApplicationLocale();
 }
 
-std::vector<std::string> App::GetPreferredSystemLanguages() const {
-  return GetPreferredLanguages();
-}
-
 std::string App::GetSystemLocale(gin_helper::ErrorThrower thrower) const {
   if (!Browser::Get()->is_ready()) {
     thrower.ThrowError(
@@ -1801,8 +1797,7 @@ gin::ObjectTemplateBuilder App::GetObjectTemplateBuilder(v8::Isolate* isolate) {
       .SetMethod("setAppLogsPath", &App::SetAppLogsPath)
       .SetMethod("setDesktopName", &App::SetDesktopName)
       .SetMethod("getLocale", &App::GetLocale)
-      .SetMethod("getPreferredSystemLanguages",
-                 &App::GetPreferredSystemLanguages)
+      .SetMethod("getPreferredSystemLanguages", &GetPreferredLanguages)
       .SetMethod("getSystemLocale", &App::GetSystemLocale)
       .SetMethod("getLocaleCountryCode", &App::GetLocaleCountryCode)
 #if BUILDFLAG(USE_NSS_CERTS)
diff --git a/shell/browser/api/electron_api_app.h b/shell/browser/api/electron_api_app.h
index eaa7e9f0afb29..40f76b19148b1 100644
--- a/shell/browser/api/electron_api_app.h
+++ b/shell/browser/api/electron_api_app.h
@@ -191,7 +191,6 @@ class App : public ElectronBrowserClient::Delegate,
   void SetDesktopName(const std::string& desktop_name);
   std::string GetLocale();
   std::string GetLocaleCountryCode();
-  std::vector<std::string> GetPreferredSystemLanguages() const;
   std::string GetSystemLocale(gin_helper::ErrorThrower thrower) const;
   void OnSecondInstance(const base::CommandLine& cmd,
                         const base::FilePath& cwd,
diff --git a/spec/api-app-spec.ts b/spec/api-app-spec.ts
index c608396bdf151..259ff09a3618b 100644
--- a/spec/api-app-spec.ts
+++ b/spec/api-app-spec.ts
@@ -132,7 +132,7 @@ describe('app module', () => {
     ifit(process.platform === 'linux')('should be empty or contain C entry', () => {
       const languages = app.getPreferredSystemLanguages();
       if (languages.length) {
-        expect(languages).to.include('C');
+        expect(languages).to.not.include('C');
       }
     });
   });

From ba74958795c108fc3a47a7388f83bcad411271fb Mon Sep 17 00:00:00 2001
From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com>
Date: Wed, 9 Nov 2022 15:51:47 +0000
Subject: [PATCH 12/12] Update the example

Co-authored-by: Raymond Zhao <7199958+rzhao271@users.noreply.github.com>
---
 docs/api/app.md | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index f364d8f12ca97..418c3504c3da9 100755
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -744,21 +744,25 @@ Therefore, this API can be used for purposes such as choosing a format for rende
 
 Returns `string[]` - The user's preferred system languages from most preferred to least preferred, including the country codes if applicable. A user can modify and add to this list on Windows or macOS through the Language and Region settings.
 
+The API uses `GlobalizationPreferences` (with a fallback to `GetSystemPreferredUILanguages`) on Windows, `\[NSLocale preferredLanguages\]` on macOS, and `g_get_language_names` on Linux.
+
 This API can be used for purposes such as deciding what language to present the application in.
 
 Here are some examples of return values of the various language and locale APIs with different configurations:
 
-* For Windows, where the application locale is French, the region is Simplified Chinese (China), and the preferred system languages from most to least preferred are French (Canada), English (US), and Simplified Chinese (China):
-  * `app.getLocale()` returns `'fr'`
-  * `app.getSystemLocale()` returns `'zh-CN'`
-  * `app.getPreferredSystemLanguages()` returns `['fr-CA', 'en-US', 'zh-Hans-CN']`
-* On macOS, where the application locale is German, the region is Finland, and the preferred system languages from most to least preferred are French, French (Canada), Simplified Chinese, and Spanish (Latin America):
+* For Windows, where the application locale is German, the regional format is Finnish (Finland), and the preferred system languages from most to least preferred are French (Canada), English (US), Simplified Chinese (China), Finnish, and Spanish (Latin America):
+  * `app.getLocale()` returns `'de'`
+  * `app.getSystemLocale()` returns `'fi-FI'`
+  * `app.getPreferredSystemLanguages()` returns `['fr-CA', 'en-US', 'zh-Hans-CN', 'fi', 'es-419']`
+* On macOS, where the application locale is German, the region is Finland, and the preferred system languages from most to least preferred are French (Canada), English (US), Simplified Chinese, and Spanish (Latin America):
   * `app.getLocale()` returns `'de'`
   * `app.getSystemLocale()` returns `'fr-FI'`
-  * `app.getPreferredSystemLanguages()` returns `['fr-FI', 'fr-CA', 'zh-Hans-FI', 'es-419']`
+  * `app.getPreferredSystemLanguages()` returns `['fr-CA', 'en-US', 'zh-Hans-FI', 'es-419']`
 
 Both the available languages and regions and the possible return values differ between the two operating systems.
 
+As can be seen with the example above, on Windows, it is possible that a preferred system language has no country code, and that one of the preferred system languages corresponds with the language used for the regional format. On macOS, the region serves more as a default country code: the user doesn't need to have Finnish as a preferred language to use Finland as the region,and the country code `FI` is used as the country code for preferred system languages that do not have associated countries in the language name.
+
 ### `app.addRecentDocument(path)` _macOS_ _Windows_
 
 * `path` string