i18n: Add --lang option to make_rst.py to write translated headings

Add a few missing headings to the translation templates.

doc/Makefile

@@ -3,6 +3,8 @@ CLASSES = $(BASEDIR)/classes/ $(BASEDIR)/../modules/
 OUTPUTDIR = $(BASEDIR)/_build
 TOOLSDIR = $(BASEDIR)/tools
 JSDIR = $(BASEDIR)/../platform/javascript
+LANGARG ?= en
+LANGCMD = -l $(LANGARG)
 
 .ONESHELL:
 
@@ -17,7 +19,7 @@ doxygen:
 rst:
 	rm -rf $(OUTPUTDIR)/rst
 	mkdir -p $(OUTPUTDIR)/rst
-	python3 $(TOOLSDIR)/make_rst.py -o $(OUTPUTDIR)/rst $(CLASSES)
+	python3 $(TOOLSDIR)/make_rst.py -o $(OUTPUTDIR)/rst $(LANGCMD) $(CLASSES)
 
 rstjs:
 	rm -rf $(OUTPUTDIR)/rstjs

doc/tools/make_rst.py

@@ -19,6 +19,28 @@
 MARKUP_ALLOWED_PRECEDENT = " -:/'\"<([{"
 MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>"
 
+# Used to translate the section headings when required with --lang argument.
+# The HEADINGS list should be synced with what we actually write with `make_heading`,
+# and also hardcoded in `doc/translations/extract.py`.
+HEADINGS = [
+    "Description",
+    "Tutorials",
+    "Properties",
+    "Constructors",
+    "Methods",
+    "Operators",
+    "Theme Properties",
+    "Signals",
+    "Enumerations",
+    "Constants",
+    "Property Descriptions",
+    "Constructor Descriptions",
+    "Method Descriptions",
+    "Operator Descriptions",
+    "Theme Property Descriptions",
+]
+headings_l10n = {}
+
 
 def print_error(error, state):  # type: (str, State) -> None
     print("ERROR: {}".format(error))
@@ -367,6 +389,7 @@ def main():  # type: () -> None
     parser = argparse.ArgumentParser()
     parser.add_argument("path", nargs="+", help="A path to an XML file or a directory containing XML files to parse.")
     parser.add_argument("--filter", default="", help="The filepath pattern for XML files to filter.")
+    parser.add_argument("--lang", "-l", default="en", help="Language to use for section headings.")
     group = parser.add_mutually_exclusive_group()
     group.add_argument("--output", "-o", default=".", help="The directory to save output .rst files in.")
     group.add_argument(
@@ -376,6 +399,25 @@ def main():  # type: () -> None
     )
     args = parser.parse_args()
 
+    # Retrieve heading translations for the given language.
+    if not args.dry_run and args.lang != "en":
+        lang_file = os.path.join(
+            os.path.dirname(os.path.realpath(__file__)), "..", "translations", "{}.po".format(args.lang)
+        )
+        if os.path.exists(lang_file):
+            try:
+                import polib
+            except ImportError:
+                print("Section heading localization requires `polib`.")
+                exit(1)
+
+            pofile = polib.pofile(lang_file)
+            for entry in pofile.translated_entries():
+                if entry.msgid in HEADINGS:
+                    headings_l10n[entry.msgid] = entry.msgstr
+        else:
+            print("No PO file at '{}' for language '{}'.".format(lang_file, args.lang))
+
     print("Checking for errors in the XML class reference...")
 
     file_list = []  # type: List[str]
@@ -467,7 +509,7 @@ def make_rst_class(class_def, state, dry_run, output_dir):  # type: (ClassDef, S
     f.write(".. The source is found in doc/classes or modules/<name>/doc_classes.\n\n")
 
     f.write(".. _class_" + class_name + ":\n\n")
-    f.write(make_heading(class_name, "="))
+    f.write(make_heading(class_name, "=", False))
 
     # Inheritance tree
     # Ascendants
@@ -1261,7 +1303,11 @@ def make_method_signature(
     return ret_type, out
 
 
-def make_heading(title, underline):  # type: (str, str) -> str
+def make_heading(title, underline, l10n=True):  # type: (str, str, bool) -> str
+    if l10n:
+        if title in headings_l10n:
+            title = headings_l10n.get(title)
+            underline *= 2  # Double length to handle wide chars.
     return title + "\n" + (underline * len(title)) + "\n\n"
 
 

doc/translations/extract.py

@@ -26,17 +26,22 @@
 """
 # Some strings used by make_rst.py are normally part of the editor translations,
 # so we need to include them manually here for the online docs.
-BASE_STRINGS = [
+HEADINGS = [
     "Description",
     "Tutorials",
     "Properties",
+    "Constructors",
     "Methods",
+    "Operators",
     "Theme Properties",
     "Signals",
     "Enumerations",
     "Constants",
     "Property Descriptions",
+    "Constructor Descriptions",
     "Method Descriptions",
+    "Operator Descriptions",
+    "Theme Property Descriptions",
 ]
 
 ## <xml-line-number-hack from="https://stackoverflow.com/a/36430270/10846399">
@@ -224,12 +229,12 @@ def _make_translation_catalog(classes):
 def _generate_translation_catalog_file(unique_msgs, output):
     with open(output, "w", encoding="utf8") as f:
         f.write(HEADER)
-        for msg in BASE_STRINGS:
+        for msg in HEADINGS:
             f.write("#: doc/tools/make_rst.py\n")
             f.write('msgid "{}"\n'.format(msg))
             f.write('msgstr ""\n\n')
         for msg in unique_msgs:
-            if len(msg) == 0 or msg in BASE_STRINGS:
+            if len(msg) == 0 or msg in HEADINGS:
                 continue
 
             f.write("#:")