i18n: Add support for translating the class reference

- Parse `.po` files from `doc/translations/*.po` like already done
  with `editor/translations/*.po`.
- Add logic to register a doc translation mapping in `TranslationServer`
  and `EditorSettings`.
- Add `DTR()` to lookup the doc translation mapping (similar to `TTR()`).
  Strings are automatically dedented and stripped of whitespace to ensure
  that they would match the translation catalog.
- Use `DTR()` to translate relevant strings in `EditorHelp`,
  `EditorInspector`, `CreateDialog`, `ConnectionsDialog`.
- Small simplification to `TranslationLoaderPO`, the path argument was
  not really meaningful.

(cherry picked from commit 4857648a16585bbd0fb2fbc33d3d0f768b8223b5)

core/io/translation_loader_po.h

@@ -37,7 +37,7 @@
 
 class TranslationLoaderPO : public ResourceFormatLoader {
 public:
-	static RES load_translation(FileAccess *f, Error *r_error);
+	static RES load_translation(FileAccess *f, Error *r_error = nullptr);
 	virtual RES load(const String &p_path, const String &p_original_path = "", Error *r_error = nullptr);
 	virtual void get_recognized_extensions(List<String> *p_extensions) const;
 	virtual bool handles_type(const String &p_type) const;

core/translation.cpp

@@ -1180,7 +1180,6 @@ void TranslationServer::setup() {
 	}
 	fallback = GLOBAL_DEF("locale/fallback", "en");
 #ifdef TOOLS_ENABLED
-
 	{
 		String options = "";
 		int idx = 0;
@@ -1194,7 +1193,6 @@ void TranslationServer::setup() {
 		ProjectSettings::get_singleton()->set_custom_property_info("locale/fallback", PropertyInfo(Variant::STRING, "locale/fallback", PROPERTY_HINT_ENUM, options));
 	}
 #endif
-	//load translations
 }
 
 void TranslationServer::set_tool_translation(const Ref<Translation> &p_translation) {
@@ -1204,12 +1202,24 @@ void TranslationServer::set_tool_translation(const Ref<Translation> &p_translati
 StringName TranslationServer::tool_translate(const StringName &p_message) const {
 	if (tool_translation.is_valid()) {
 		StringName r = tool_translation->get_message(p_message);
-
 		if (r) {
 			return r;
 		}
 	}
+	return p_message;
+}
+
+void TranslationServer::set_doc_translation(const Ref<Translation> &p_translation) {
+	doc_translation = p_translation;
+}
 
+StringName TranslationServer::doc_translate(const StringName &p_message) const {
+	if (doc_translation.is_valid()) {
+		StringName r = doc_translation->get_message(p_message);
+		if (r) {
+			return r;
+		}
+	}
 	return p_message;
 }
 

core/translation.h

@@ -71,6 +71,7 @@ class TranslationServer : public Object {
 
 	Set<Ref<Translation>> translations;
 	Ref<Translation> tool_translation;
+	Ref<Translation> doc_translation;
 
 	Map<String, String> locale_name_map;
 
@@ -107,6 +108,8 @@ public:
 
 	void set_tool_translation(const Ref<Translation> &p_translation);
 	StringName tool_translate(const StringName &p_message) const;
+	void set_doc_translation(const Ref<Translation> &p_translation);
+	StringName doc_translate(const StringName &p_message) const;
 
 	void setup();
 

core/ustring.cpp

@@ -4469,6 +4469,15 @@ String TTR(const String &p_text) {
 	return p_text;
 }
 
+String DTR(const String &p_text) {
+	if (TranslationServer::get_singleton()) {
+		// Comes straight from the XML, so remove indentation and any trailing whitespace.
+		const String text = p_text.dedent().strip_edges();
+		return TranslationServer::get_singleton()->doc_translate(text);
+	}
+
+	return p_text;
+}
 #endif
 
 String RTR(const String &p_text) {

core/ustring.h

@@ -414,25 +414,25 @@ _FORCE_INLINE_ bool is_str_less(const L *l_ptr, const R *r_ptr) {
 
 /* end of namespace */
 
-//tool translate
+// Tool translate (TTR and variants) for the editor UI,
+// and doc translate for the class reference (DTR).
 #ifdef TOOLS_ENABLED
-
-//gets parsed
+// Gets parsed.
 String TTR(const String &);
-//use for C strings
+String DTR(const String &);
+// Use for C strings.
 #define TTRC(m_value) (m_value)
-//use to avoid parsing (for use later with C strings)
+// Use to avoid parsing (for use later with C strings).
 #define TTRGET(m_value) TTR(m_value)
 
 #else
-
 #define TTR(m_value) (String())
+#define DTR(m_value) (String())
 #define TTRC(m_value) (m_value)
 #define TTRGET(m_value) (m_value)
-
 #endif
 
-//tool or regular translate
+// Runtime translate for the public node API.
 String RTR(const String &);
 
 bool is_symbol(CharType c);

editor/SCsub

@@ -69,10 +69,19 @@ if env["tools"]:
 
     path = env.Dir(".").abspath
 
-    # Translations
+    # Editor translations
     tlist = glob.glob(path + "/translations/*.po")
-    env.Depends("#editor/translations.gen.h", tlist)
-    env.CommandNoCache("#editor/translations.gen.h", tlist, run_in_subprocess(editor_builders.make_translations_header))
+    env.Depends("#editor/editor_translations.gen.h", tlist)
+    env.CommandNoCache(
+        "#editor/editor_translations.gen.h", tlist, run_in_subprocess(editor_builders.make_editor_translations_header)
+    )
+
+    # Documentation translations
+    tlist = glob.glob(env.Dir("#doc").abspath + "/translations/*.po")
+    env.Depends("#editor/doc_translations.gen.h", tlist)
+    env.CommandNoCache(
+        "#editor/doc_translations.gen.h", tlist, run_in_subprocess(editor_builders.make_doc_translations_header)
+    )
 
     # Fonts
     flist = glob.glob(path + "/../thirdparty/fonts/*.ttf")

editor/connections_dialog.cpp

@@ -1001,7 +1001,7 @@ void ConnectionsDock::update_tree() {
 					while (F && descr == String()) {
 						for (int i = 0; i < F->get().signals.size(); i++) {
 							if (F->get().signals[i].name == signal_name.operator String()) {
-								descr = F->get().signals[i].description.strip_edges();
+								descr = DTR(F->get().signals[i].description.strip_edges());
 								break;
 							}
 						}

editor/create_dialog.cpp

@@ -247,7 +247,7 @@ void CreateDialog::add_type(const String &p_type, HashMap<String, TreeItem *> &p
 		item->set_collapsed(collapse);
 	}
 
-	const String &description = EditorHelp::get_doc_data()->class_list[p_type].brief_description;
+	const String &description = DTR(EditorHelp::get_doc_data()->class_list[p_type].brief_description);
 	item->set_tooltip(0, description);
 
 	String icon_fallback = has_icon(base_type, "EditorIcons") ? base_type : "Object";
@@ -555,11 +555,11 @@ void CreateDialog::_item_selected() {
 		return;
 	}
 
-	if (EditorHelp::get_doc_data()->class_list.has(name) && !EditorHelp::get_doc_data()->class_list[name].brief_description.empty()) {
-		help_bit->set_text(EditorHelp::get_doc_data()->class_list[name].brief_description);
+	const String brief_desc = DTR(EditorHelp::get_doc_data()->class_list[name].brief_description);
+	if (!brief_desc.empty()) {
 		// Display both class name and description, since the help bit may be displayed
 		// far away from the location (especially if the dialog was resized to be taller).
-		help_bit->set_text(vformat("[b]%s[/b]: %s", name, EditorHelp::get_doc_data()->class_list[name].brief_description.strip_edges()));
+		help_bit->set_text(vformat("[b]%s[/b]: %s", name, brief_desc));
 		help_bit->get_rich_text()->set_self_modulate(Color(1, 1, 1, 1));
 	} else {
 		// Use nested `vformat()` as translators shouldn't interfere with BBCode tags.

editor/editor_builders.py

@@ -74,15 +74,15 @@ def make_fonts_header(target, source, env):
     g.close()
 
 
-def make_translations_header(target, source, env):
+def make_translations_header(target, source, env, category):
 
     dst = target[0]
 
     g = open_utf8(dst, "w")
 
     g.write("/* THIS FILE IS GENERATED DO NOT EDIT */\n")
-    g.write("#ifndef _EDITOR_TRANSLATIONS_H\n")
-    g.write("#define _EDITOR_TRANSLATIONS_H\n")
+    g.write("#ifndef _{}_TRANSLATIONS_H\n".format(category.upper()))
+    g.write("#define _{}_TRANSLATIONS_H\n".format(category.upper()))
 
     import zlib
     import os.path
@@ -97,7 +97,7 @@ def make_translations_header(target, source, env):
         buf = zlib.compress(buf)
         name = os.path.splitext(os.path.basename(sorted_paths[i]))[0]
 
-        g.write("static const unsigned char _translation_" + name + "_compressed[] = {\n")
+        g.write("static const unsigned char _{}_translation_{}_compressed[] = {{\n".format(category, name))
         for j in range(len(buf)):
             g.write("\t" + byte_to_str(buf[j]) + ",\n")
 
@@ -105,15 +105,17 @@ def make_translations_header(target, source, env):
 
         xl_names.append([name, len(buf), str(decomp_size)])
 
-    g.write("struct EditorTranslationList {\n")
+    g.write("struct {}TranslationList {{\n".format(category.capitalize()))
     g.write("\tconst char* lang;\n")
     g.write("\tint comp_size;\n")
     g.write("\tint uncomp_size;\n")
     g.write("\tconst unsigned char* data;\n")
     g.write("};\n\n")
-    g.write("static EditorTranslationList _editor_translations[] = {\n")
+    g.write("static {}TranslationList _{}_translations[] = {{\n".format(category.capitalize(), category))
     for x in xl_names:
-        g.write('\t{ "' + x[0] + '", ' + str(x[1]) + ", " + str(x[2]) + ", _translation_" + x[0] + "_compressed},\n")
+        g.write(
+            '\t{{ "{}", {}, {}, _{}_translation_{}_compressed }},\n'.format(x[0], str(x[1]), str(x[2]), category, x[0])
+        )
     g.write("\t{NULL, 0, 0, NULL}\n")
     g.write("};\n")
 
@@ -122,5 +124,13 @@ def make_translations_header(target, source, env):
     g.close()
 
 
+def make_editor_translations_header(target, source, env):
+    make_translations_header(target, source, env, "editor")
+
+
+def make_doc_translations_header(target, source, env):
+    make_translations_header(target, source, env, "doc")
+
+
 if __name__ == "__main__":
     subprocess_main(globals())

editor/editor_help.cpp

@@ -423,7 +423,7 @@ void EditorHelp::_update_doc() {
 		class_desc->push_color(text_color);
 		class_desc->push_font(doc_bold_font);
 		class_desc->push_indent(1);
-		_add_text(cd.brief_description);
+		_add_text(DTR(cd.brief_description));
 		class_desc->pop();
 		class_desc->pop();
 		class_desc->pop();
@@ -447,7 +447,7 @@ void EditorHelp::_update_doc() {
 		class_desc->push_color(text_color);
 		class_desc->push_font(doc_font);
 		class_desc->push_indent(1);
-		_add_text(cd.description);
+		_add_text(DTR(cd.description));
 		class_desc->pop();
 		class_desc->pop();
 		class_desc->pop();
@@ -469,8 +469,8 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 
 		for (int i = 0; i < cd.tutorials.size(); i++) {
-			const String link = cd.tutorials[i].link;
-			String linktxt = (cd.tutorials[i].title.empty()) ? link : cd.tutorials[i].title;
+			const String link = DTR(cd.tutorials[i].link);
+			String linktxt = (cd.tutorials[i].title.empty()) ? link : DTR(cd.tutorials[i].title);
 			const int seppos = linktxt.find("//");
 			if (seppos != -1) {
 				linktxt = link.right(seppos + 2);
@@ -712,7 +712,7 @@ void EditorHelp::_update_doc() {
 				class_desc->push_font(doc_font);
 				class_desc->add_text("  ");
 				class_desc->push_color(comment_color);
-				_add_text(cd.theme_properties[i].description);
+				_add_text(DTR(cd.theme_properties[i].description));
 				class_desc->pop();
 				class_desc->pop();
 			}
@@ -779,7 +779,7 @@ void EditorHelp::_update_doc() {
 				class_desc->push_font(doc_font);
 				class_desc->push_color(comment_color);
 				class_desc->push_indent(1);
-				_add_text(cd.signals[i].description);
+				_add_text(DTR(cd.signals[i].description));
 				class_desc->pop(); // indent
 				class_desc->pop();
 				class_desc->pop(); // font
@@ -872,7 +872,7 @@ void EditorHelp::_update_doc() {
 						//class_desc->add_text("  ");
 						class_desc->push_indent(1);
 						class_desc->push_color(comment_color);
-						_add_text(enum_list[i].description);
+						_add_text(DTR(enum_list[i].description));
 						class_desc->pop();
 						class_desc->pop();
 						class_desc->pop(); // indent
@@ -937,7 +937,7 @@ void EditorHelp::_update_doc() {
 					class_desc->push_font(doc_font);
 					class_desc->push_indent(1);
 					class_desc->push_color(comment_color);
-					_add_text(constants[i].description);
+					_add_text(DTR(constants[i].description));
 					class_desc->pop();
 					class_desc->pop();
 					class_desc->pop(); // indent
@@ -1066,7 +1066,7 @@ void EditorHelp::_update_doc() {
 			class_desc->push_font(doc_font);
 			class_desc->push_indent(1);
 			if (cd.properties[i].description.strip_edges() != String()) {
-				_add_text(cd.properties[i].description);
+				_add_text(DTR(cd.properties[i].description));
 			} else {
 				class_desc->add_image(get_icon("Error", "EditorIcons"));
 				class_desc->add_text(" ");
@@ -1117,7 +1117,7 @@ void EditorHelp::_update_doc() {
 				class_desc->push_font(doc_font);
 				class_desc->push_indent(1);
 				if (methods_filtered[i].description.strip_edges() != String()) {
-					_add_text(methods_filtered[i].description);
+					_add_text(DTR(methods_filtered[i].description));
 				} else {
 					class_desc->add_image(get_icon("Error", "EditorIcons"));
 					class_desc->add_text(" ");

editor/editor_inspector.cpp

@@ -1490,7 +1490,7 @@ void EditorInspector::update_tree() {
 					if (E) {
 						descr = E->get().brief_description;
 					}
-					class_descr_cache[type2] = descr;
+					class_descr_cache[type2] = DTR(descr);
 				}
 
 				category->set_tooltip(p.name + "::" + (class_descr_cache[type2] == "" ? "" : class_descr_cache[type2]));
@@ -1645,7 +1645,7 @@ void EditorInspector::update_tree() {
 				while (F && descr == String()) {
 					for (int i = 0; i < F->get().properties.size(); i++) {
 						if (F->get().properties[i].name == propname.operator String()) {
-							descr = F->get().properties[i].description.strip_edges();
+							descr = DTR(F->get().properties[i].description.strip_edges());
 							break;
 						}
 					}
@@ -1655,7 +1655,7 @@ void EditorInspector::update_tree() {
 						// Likely a theme property.
 						for (int i = 0; i < F->get().theme_properties.size(); i++) {
 							if (F->get().theme_properties[i].name == slices[1]) {
-								descr = F->get().theme_properties[i].description.strip_edges();
+								descr = DTR(F->get().theme_properties[i].description.strip_edges());
 								break;
 							}
 						}

editor/editor_settings.cpp

@@ -44,8 +44,9 @@
 #include "core/os/os.h"
 #include "core/project_settings.h"
 #include "core/version.h"
+#include "editor/doc_translations.gen.h"
 #include "editor/editor_node.h"
-#include "editor/translations.gen.h"
+#include "editor/editor_translations.gen.h"
 #include "scene/main/node.h"
 #include "scene/main/scene_tree.h"
 #include "scene/main/viewport.h"
@@ -1002,11 +1003,11 @@ fail:
 void EditorSettings::setup_language() {
 	String lang = get("interface/editor/editor_language");
 	if (lang == "en") {
-		return; //none to do
+		return; // Default, nothing to do.
 	}
 
+	// Load editor translation for configured/detected locale.
 	EditorTranslationList *etl = _editor_translations;
-
 	while (etl->data) {
 		if (etl->lang == lang) {
 			Vector<uint8_t> data;
@@ -1016,7 +1017,7 @@ void EditorSettings::setup_language() {
 			FileAccessMemory *fa = memnew(FileAccessMemory);
 			fa->open_custom(data.ptr(), data.size());
 
-			Ref<Translation> tr = TranslationLoaderPO::load_translation(fa, nullptr);
+			Ref<Translation> tr = TranslationLoaderPO::load_translation(fa);
 
 			if (tr.is_valid()) {
 				tr->set_locale(etl->lang);
@@ -1027,6 +1028,29 @@ void EditorSettings::setup_language() {
 
 		etl++;
 	}
+
+	// Load class reference translation.
+	DocTranslationList *dtl = _doc_translations;
+	while (dtl->data) {
+		if (dtl->lang == lang) {
+			Vector<uint8_t> data;
+			data.resize(dtl->uncomp_size);
+			Compression::decompress(data.ptrw(), dtl->uncomp_size, dtl->data, dtl->comp_size, Compression::MODE_DEFLATE);
+
+			FileAccessMemory *fa = memnew(FileAccessMemory);
+			fa->open_custom(data.ptr(), data.size());
+
+			Ref<Translation> tr = TranslationLoaderPO::load_translation(fa);
+
+			if (tr.is_valid()) {
+				tr->set_locale(dtl->lang);
+				TranslationServer::get_singleton()->set_doc_translation(tr);
+				break;
+			}
+		}
+
+		dtl++;
+	}
 }
 
 void EditorSettings::setup_network() {