Merge pull request #52740 from akien-mga/os-get_locale-language

Implement `OS::get_locale_language()` helper method

6 files changed, 26 insertions, 4 deletions

diff --git a/core/core_bind.cpp b/core/core_bind.cpp
index 58aecf39aa..e029b85450 100644
--- a/core/core_bind.cpp
+++ b/core/core_bind.cpp
@@ -286,6 +286,10 @@ String OS::get_locale() const {
 	return ::OS::get_singleton()->get_locale();
 }
 
+String OS::get_locale_language() const {
+	return ::OS::get_singleton()->get_locale_language();
+}
+
 String OS::get_model_name() const {
 	return ::OS::get_singleton()->get_model_name();
 }
@@ -547,6 +551,7 @@ void OS::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("delay_usec", "usec"), &OS::delay_usec);
 	ClassDB::bind_method(D_METHOD("delay_msec", "msec"), &OS::delay_msec);
 	ClassDB::bind_method(D_METHOD("get_locale"), &OS::get_locale);
+	ClassDB::bind_method(D_METHOD("get_locale_language"), &OS::get_locale_language);
 	ClassDB::bind_method(D_METHOD("get_model_name"), &OS::get_model_name);
 
 	ClassDB::bind_method(D_METHOD("is_userfs_persistent"), &OS::is_userfs_persistent);
diff --git a/core/core_bind.h b/core/core_bind.h
index 8e95629695..a5d5a7c8ce 100644
--- a/core/core_bind.h
+++ b/core/core_bind.h
@@ -178,6 +178,7 @@ public:
 	Vector<String> get_cmdline_args();
 
 	String get_locale() const;
+	String get_locale_language() const;
 
 	String get_model_name() const;
 
diff --git a/core/os/os.cpp b/core/os/os.cpp
index dc3fe29dca..7505f3ff34 100644
--- a/core/os/os.cpp
+++ b/core/os/os.cpp
@@ -231,6 +231,12 @@ String OS::get_locale() const {
 	return "en";
 }
 
+// Non-virtual helper to extract the 2 or 3-letter language code from
+// `get_locale()` in a way that's consistent for all platforms.
+String OS::get_locale_language() const {
+	return get_locale().left(3).replace("_", "");
+}
+
 // Helper function to ensure that a dir name/path will be valid on the OS
 String OS::get_safe_dir_name(const String &p_dir_name, bool p_allow_dir_separator) const {
 	Vector<String> invalid_chars = String(": * ? \" < > |").split(" ");
diff --git a/core/os/os.h b/core/os/os.h
index f585483300..c027428477 100644
--- a/core/os/os.h
+++ b/core/os/os.h
@@ -243,6 +243,7 @@ public:
 	RenderThreadMode get_render_thread_mode() const { return _render_thread_mode; }
 
 	virtual String get_locale() const;
+	String get_locale_language() const;
 
 	String get_safe_dir_name(const String &p_dir_name, bool p_allow_dir_separator = false) const;
 	virtual String get_godot_dir_name() const;
diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml
index 757730f6c8..305258c8c5 100644
--- a/doc/classes/OS.xml
+++ b/doc/classes/OS.xml
@@ -215,7 +215,7 @@
 		<method name="get_locale" qualifiers="const">
 			<return type="String" />
 			<description>
-				Returns the host OS locale as a string of the form [code]language_Script_COUNTRY_VARIANT@extra[/code].
+				Returns the host OS locale as a string of the form [code]language_Script_COUNTRY_VARIANT@extra[/code]. If you want only the language code and not the fully specified locale from the OS, you can use [method get_locale_language].
 				[code]language[/code] - 2 or 3-letter [url=https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes]language code[/url], in lower case.
 				[code]Script[/code] - optional, 4-letter [url=https://en.wikipedia.org/wiki/ISO_15924]script code[/url], in title case.
 				[code]COUNTRY[/code] - optional, 2 or 3-letter [url=https://en.wikipedia.org/wiki/ISO_3166-1]country code[/url], in upper case.
@@ -223,6 +223,13 @@
 				[code]extra[/code] - optional, semicolon separated list of additional key words. Currency, calendar, sort order and numbering system information.
 			</description>
 		</method>
+		<method name="get_locale_language" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns the host OS locale's 2 or 3-letter [url=https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes]language code[/url] as a string which should be consistent on all platforms. This is equivalent to extracting the [code]language[/code] part of the [method get_locale] string.
+				This can be used to narrow down fully specified locale strings to only the "common" language code, when you don't need the additional information about country code or variants. For example, for a French Canadian user with [code]fr_CA[/code] locale, this would return [code]fr[/code].
+			</description>
+		</method>
 		<method name="get_model_name" qualifiers="const">
 			<return type="String" />
 			<description>
diff --git a/doc/classes/TranslationServer.xml b/doc/classes/TranslationServer.xml
index 029848be33..a002166664 100644
--- a/doc/classes/TranslationServer.xml
+++ b/doc/classes/TranslationServer.xml
@@ -27,13 +27,14 @@
 		<method name="get_loaded_locales" qualifiers="const">
 			<return type="Array" />
 			<description>
-				Returns an Array of all loaded locales of the game.
+				Returns an array of all loaded locales of the project.
 			</description>
 		</method>
 		<method name="get_locale" qualifiers="const">
 			<return type="String" />
 			<description>
-				Returns the current locale of the game.
+				Returns the current locale of the project.
+				See also [method OS.get_locale] and [method OS.get_locale_language] to query the locale of the user system.
 			</description>
 		</method>
 		<method name="get_locale_name" qualifiers="const">
@@ -75,7 +76,8 @@
 			<return type="void" />
 			<argument index="0" name="locale" type="String" />
 			<description>
-				Sets the locale of the game.
+				Sets the locale of the project. The [code]locale[/code] string will be standardized to match known locales (e.g. [code]en-US[/code] would be matched to [code]en_US[/code]).
+				If translations have been loaded beforehand for the new locale, they will be applied.
 			</description>
 		</method>
 		<method name="translate" qualifiers="const">