From b98785309f9e8f64299fa39403266cc743bde722 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Tue, 21 Dec 2021 10:53:07 +0100 Subject: [PATCH] i18n: Add `--lang` option to `make_rst.py` to write translated headings Add a few missing headings to the translation templates. --- doc/Makefile | 4 ++- doc/tools/make_rst.py | 50 +++++++++++++++++++++++++++++++++++-- doc/translations/extract.py | 11 +++++--- 3 files changed, 59 insertions(+), 6 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index c46a485da1a..c29843f303f 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: @@ -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 diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index e5e59198f69..3b965f0dba6 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -19,6 +19,28 @@ 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", + "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//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" diff --git a/doc/translations/extract.py b/doc/translations/extract.py index 68ac5d59f53..6550cff5aa5 100644 --- a/doc/translations/extract.py +++ b/doc/translations/extract.py @@ -26,17 +26,22 @@ 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", + "Constructors", "Methods", + "Operators", "Theme Properties", "Signals", "Enumerations", "Constants", "Property Descriptions", + "Constructor Descriptions", "Method Descriptions", + "Operator Descriptions", + "Theme Property Descriptions", ] ## @@ -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("#:")