diff --git a/doc/Makefile b/doc/Makefile index 87a442389e2..04dfcf850c2 100644 --- a/doc/Makefile +++ b/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: @@ -24,7 +26,7 @@ markdown: 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 diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 1b9a1807054..f06af56e510 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -19,6 +19,24 @@ GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$") 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", + "Methods", + "Theme Properties", + "Signals", + "Enumerations", + "Constants", + "Property Descriptions", + "Method Descriptions", + "Theme Property Descriptions", +] +headings_l10n = {} + def print_error(error, state): # type: (str, State) -> None print("ERROR: {}".format(error)) @@ -309,6 +327,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( @@ -318,6 +337,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] @@ -409,7 +447,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//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 @@ -1084,7 +1122,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" diff --git a/doc/translations/extract.py b/doc/translations/extract.py index d53ee914889..4c5264f4e98 100644 --- a/doc/translations/extract.py +++ b/doc/translations/extract.py @@ -26,7 +26,7 @@ msgstr "" """ # 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", @@ -37,6 +37,7 @@ BASE_STRINGS = [ "Constants", "Property Descriptions", "Method Descriptions", + "Theme Property Descriptions", ] ## @@ -224,12 +225,12 @@ def _make_translation_catalog(classes): def _generate_translation_catalog_file(unique_msgs, output, location_line=False): 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("#:")