Merge pull request #40443 from SkyLucilfer/PluralsSupport

Added plurals and context support to Translation

4 files changed, 108 insertions, 8 deletions

diff --git a/doc/classes/EditorTranslationParserPlugin.xml b/doc/classes/EditorTranslationParserPlugin.xml
index d40fc558de..f5204e7bab 100644
--- a/doc/classes/EditorTranslationParserPlugin.xml
+++ b/doc/classes/EditorTranslationParserPlugin.xml
@@ -5,30 +5,41 @@
 	</brief_description>
 	<description>
 		Plugins are registered via [method EditorPlugin.add_translation_parser_plugin] method. To define the parsing and string extraction logic, override the [method parse_file] method in script.
+		Add the extracted strings to argument [code]msgids[/code] or [code]msgids_context_plural[/code] if context or plural is used.
+		When adding to [code]msgids_context_plural[/code], you must add the data using the format [code]["A", "B", "C"][/code], where [code]A[/code] represents the extracted string, [code]B[/code] represents the context, and [code]C[/code] represents the plural version of the extracted string. If you want to add only context but not plural, put [code]""[/code] for the plural slot. The idea is the same if you only want to add plural but not context. See the code below for concrete examples.
 		The extracted strings will be written into a POT file selected by user under "POT Generation" in "Localization" tab in "Project Settings" menu.
-		Below shows an example of a custom parser that extracts strings in a CSV file to write into a POT.
+		Below shows an example of a custom parser that extracts strings from a CSV file to write into a POT.
 		[codeblock]
 		tool
 		extends EditorTranslationParserPlugin
 
 
-		func parse_file(path, extracted_strings):
+		func parse_file(path, msgids, msgids_context_plural):
 		    var file = File.new()
 		    file.open(path, File.READ)
 		    var text = file.get_as_text()
 		    var split_strs = text.split(",", false, 0)
 		    for s in split_strs:
-		        extracted_strings.append(s)
+		        msgids.append(s)
 		        #print("Extracted string: " + s)
 
 
 		func get_recognized_extensions():
 		    return ["csv"]
 		[/codeblock]
+		To add a translatable string associated with context or plural, add it to [code]msgids_context_plural[/code]:
+		[codeblock]
+		# This will add a message with msgid "Test 1", msgctxt "context", and msgid_plural "test 1 plurals".
+		msgids_context_plural.append(["Test 1", "context", "test 1 plurals"])
+		# This will add a message with msgid "A test without context" and msgid_plural "plurals".
+		msgids_context_plural.append(["A test without context", "", "plurals"])
+		# This will add a message with msgid "Only with context" and msgctxt "a friendly context".
+		msgids_context_plural.append(["Only with context", "a friendly context", ""])
+		[/codeblock]
 		[b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [File] type.
 		For example:
 		[codeblock]
-		func parse_file(path, extracted_strings):
+		func parse_file(path, msgids, msgids_context_plural):
 		    var res = ResourceLoader.load(path, "Script")
 		    var text = res.get_source_code()
 		    # Parsing logic.
@@ -53,7 +64,9 @@
 			</return>
 			<argument index="0" name="path" type="String">
 			</argument>
-			<argument index="1" name="extracted_strings" type="Array">
+			<argument index="1" name="msgids" type="Array">
+			</argument>
+			<argument index="2" name="msgids_context_plural" type="Array">
 			</argument>
 			<description>
 				Override this method to define a custom parsing logic to extract the translatable strings.
diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml
index ca6b624359..077067a0f4 100644
--- a/doc/classes/Object.xml
+++ b/doc/classes/Object.xml
@@ -486,13 +486,35 @@
 			</description>
 		</method>
 		<method name="tr" qualifiers="const">
-			<return type="StringName">
+			<return type="String">
 			</return>
 			<argument index="0" name="message" type="StringName">
 			</argument>
+			<argument index="1" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
 			<description>
-				Translates a message using translation catalogs configured in the Project Settings.
+				Translates a message using translation catalogs configured in the Project Settings. An additional context could be used to specify the translation context.
 				Only works if message translation is enabled (which it is by default), otherwise it returns the [code]message[/code] unchanged. See [method set_message_translation].
+				See <link>https://docs.godotengine.org/en/latest/tutorials/i18n/internationalizing_games.html</link> for examples of the usage of this method.
+			</description>
+		</method>
+		<method name="tr_n" qualifiers="const">
+			<return type="String">
+			</return>
+			<argument index="0" name="message" type="StringName">
+			</argument>
+			<argument index="1" name="plural_message" type="StringName">
+			</argument>
+			<argument index="2" name="n" type="int">
+			</argument>
+			<argument index="3" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
+			<description>
+				Translates a message involving plurals using translation catalogs configured in the Project Settings. An additional context could be used to specify the translation context.
+				Only works if message translation is enabled (which it is by default), otherwise it returns the [code]message[/code] or [code]plural_message[/code] unchanged. See [method set_message_translation].
+				The number [code]n[/code] is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language.
+				[b]Note:[/b] Negative and floating-point values usually represent physical entities for which singular and plural don't clearly apply. In such cases, use [method tr].
+				See <link>https://docs.godotengine.org/en/latest/tutorials/i18n/localization_using_gettext.html</link> for examples of the usage of this method.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/Translation.xml b/doc/classes/Translation.xml
index 11245195bf..1989a63362 100644
--- a/doc/classes/Translation.xml
+++ b/doc/classes/Translation.xml
@@ -18,8 +18,25 @@
 			</argument>
 			<argument index="1" name="xlated_message" type="StringName">
 			</argument>
+			<argument index="2" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
 			<description>
 				Adds a message if nonexistent, followed by its translation.
+				An additional context could be used to specify the translation context or differentiate polysemic words.
+			</description>
+		</method>
+		<method name="add_plural_message">
+			<return type="void">
+			</return>
+			<argument index="0" name="src_message" type="StringName">
+			</argument>
+			<argument index="1" name="xlated_messages" type="PackedStringArray">
+			</argument>
+			<argument index="2" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
+			<description>
+				Adds a message involving plural translation if nonexistent, followed by its translation.
+				An additional context could be used to specify the translation context or differentiate polysemic words.
 			</description>
 		</method>
 		<method name="erase_message">
@@ -27,6 +44,8 @@
 			</return>
 			<argument index="0" name="src_message" type="StringName">
 			</argument>
+			<argument index="1" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
 			<description>
 				Erases a message.
 			</description>
@@ -36,6 +55,8 @@
 			</return>
 			<argument index="0" name="src_message" type="StringName">
 			</argument>
+			<argument index="1" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
 			<description>
 				Returns a message's translation.
 			</description>
@@ -54,6 +75,22 @@
 				Returns all the messages (keys).
 			</description>
 		</method>
+		<method name="get_plural_message" qualifiers="const">
+			<return type="StringName">
+			</return>
+			<argument index="0" name="src_message" type="StringName">
+			</argument>
+			<argument index="1" name="src_plural_message" type="StringName">
+			</argument>
+			<argument index="2" name="n" type="int">
+			</argument>
+			<argument index="3" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
+			<description>
+				Returns a message's translation involving plurals.
+				The number [code]n[/code] is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language.
+			</description>
+		</method>
 	</methods>
 	<members>
 		<member name="locale" type="String" setter="set_locale" getter="get_locale" default="&quot;en&quot;">
diff --git a/doc/classes/TranslationServer.xml b/doc/classes/TranslationServer.xml
index aaf7a4d160..3369663af6 100644
--- a/doc/classes/TranslationServer.xml
+++ b/doc/classes/TranslationServer.xml
@@ -50,6 +50,16 @@
 				Returns a locale's language and its variant (e.g. [code]"en_US"[/code] would return [code]"English (United States)"[/code]).
 			</description>
 		</method>
+		<method name="get_translation_object">
+			<return type="Translation">
+			</return>
+			<argument index="0" name="locale" type="String">
+			</argument>
+			<description>
+				Returns the [Translation] instance based on the [code]locale[/code] passed in.
+				It will return a [code]nullptr[/code] if there is no [Translation] instance that matches the [code]locale[/code].
+			</description>
+		</method>
 		<method name="remove_translation">
 			<return type="void">
 			</return>
@@ -73,8 +83,26 @@
 			</return>
 			<argument index="0" name="message" type="StringName">
 			</argument>
+			<argument index="1" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
+			<description>
+				Returns the current locale's translation for the given message (key) and context.
+			</description>
+		</method>
+		<method name="translate_plural" qualifiers="const">
+			<return type="StringName">
+			</return>
+			<argument index="0" name="message" type="StringName">
+			</argument>
+			<argument index="1" name="plural_message" type="StringName">
+			</argument>
+			<argument index="2" name="n" type="int">
+			</argument>
+			<argument index="3" name="context" type="StringName" default="&quot;&quot;">
+			</argument>
 			<description>
-				Returns the current locale's translation for the given message (key).
+				Returns the current locale's translation for the given message (key), plural_message and context.
+				The number [code]n[/code] is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language.
 			</description>
 		</method>
 	</methods>