From a7cb64c16770a27df4526eabe506859c831faf7c Mon Sep 17 00:00:00 2001
From: Sab Pyrope <sab.pyrope@gmail.com>
Date: Sat, 2 Nov 2024 14:28:15 +0800
Subject: [PATCH] Add 'obsolete' comments in translations

---
 doc/OBSOLETION_AND_MIGRATION.md     | 15 +++++++++++
 lang/extract_json_strings.py        | 10 +++++++-
 lang/string_extractor/pot_export.py | 39 +++++++++++++++++++++++++----
 lang/update_pot.sh                  |  2 ++
 4 files changed, 60 insertions(+), 6 deletions(-)

diff --git a/doc/OBSOLETION_AND_MIGRATION.md b/doc/OBSOLETION_AND_MIGRATION.md
index 37f44b937d980..113f0a85358bb 100644
--- a/doc/OBSOLETION_AND_MIGRATION.md
+++ b/doc/OBSOLETION_AND_MIGRATION.md
@@ -288,3 +288,18 @@ For mods, you need to add an `"obsolete": true,` boolean into MOD_INFO, which pr
     "obsolete": true
   }
 ```
+
+When declaring a mod obsolete, also consider adding its directory to the `lang/update_pot.sh` file via the `-D` argument to `extract_json_strings.py`:
+
+```diff
+echo "> Extracting strings from JSON"
+if ! lang/extract_json_strings.py \
+        -i data \
+        ...
+        -D data/mods/BlazeIndustries \
+        -D data/mods/desert_region \
++       -D data/mods/YOUR_DEPRECATED_MOD \
+        -n "$package $version" \
+        -r lang/po/gui.pot \
+        -o lang/po/json.pot
+```
diff --git a/lang/extract_json_strings.py b/lang/extract_json_strings.py
index ed1a27d4f701f..bdb05fd13f81b 100755
--- a/lang/extract_json_strings.py
+++ b/lang/extract_json_strings.py
@@ -24,6 +24,9 @@
 parser.add_option("-x", "--exclude_dir", dest="exclude_dir",
                   action="append", type="str",
                   help="exclude directories")
+parser.add_option("-D", "--obsolete_paths", dest="obsolete_paths",
+                  action="append", type="str",
+                  help="obsolete directories or files")
 
 (options, args) = parser.parse_args()
 
@@ -46,6 +49,9 @@
 exclude_dir = [os.path.normpath(i) for i in options.exclude_dir] \
     if options.exclude_dir else []
 
+obsolete_paths = [os.path.normpath(i) for i in options.obsolete_paths] \
+    if options.obsolete_paths else []
+
 
 def extract_all_from_dir(json_dir):
     """Extract strings from every json file in the specified directory,
@@ -72,7 +78,9 @@ def main():
         extract_all_from_dir(i)
 
     with open(options.output, mode="w", encoding="utf-8") as fp:
-        write_to_pot(fp, True, options.name, sanitize=options.reference)
+        write_to_pot(fp, True, options.name,
+                     sanitize=options.reference,
+                     obsolete_paths=obsolete_paths)
 
 
 main()
diff --git a/lang/string_extractor/pot_export.py b/lang/string_extractor/pot_export.py
index ad881d037f064..58f979a15deb0 100644
--- a/lang/string_extractor/pot_export.py
+++ b/lang/string_extractor/pot_export.py
@@ -7,14 +7,42 @@
 from .message import messages, occurrences
 
 
-def deduplciate(comments):
-    """Remove duplicate comment lines while preserving order."""
-    seen = set()
+def process_comments(comments, origins, obsolete_paths):
     result = []
+
+    # remove duplicate comment lines while preserving order
+    seen = set()
     for comment in comments:
         if comment not in seen:
             result.append(comment)
             seen.add(comment)
+
+    # add 'obsolete' comment if this string
+    # has only obsolete files in the origins
+    obsolete_count = 0
+    for origin in origins:
+        is_obsolete = False
+
+        if "obsolet" in origin:
+            # if the file path contains "obsolete"/"obsoletion"
+            is_obsolete = True
+        else:
+            # if the file path matches the obsolete paths
+            # explicitly specified in the '-D' arguments
+            for o_path in obsolete_paths:
+                p = os.path.commonpath([o_path, origin])
+                if p in obsolete_paths:
+                    is_obsolete = True
+                    break
+        if is_obsolete:
+            obsolete_count += 1
+
+    if obsolete_count == len(origins):
+        return [
+            "[DEPRECATED] Don't translate this line.",
+            "This string is from an obsolete source "
+            "and will no longer be used in the game."
+        ]
     return result
 
 
@@ -71,7 +99,8 @@ def sanitize_plural_colissions(reference):
                         messages[pair][0].text_plural = entry.msgid_plural
 
 
-def write_to_pot(fp, with_header=True, pkg_name=None, sanitize=None):
+def write_to_pot(fp, with_header=True, pkg_name=None,
+                 sanitize=None, obsolete_paths=[]):
     if sanitize:
         sanitize_plural_colissions(sanitize)
     if with_header:
@@ -93,7 +122,7 @@ def write_to_pot(fp, with_header=True, pkg_name=None, sanitize=None):
         origin = " ".join(sorted(origins))
 
         # translator comments
-        for line in deduplciate(comments):
+        for line in process_comments(comments, origins, obsolete_paths):
             print("#. ~ {}".format(line), file=fp)
 
         # reference
diff --git a/lang/update_pot.sh b/lang/update_pot.sh
index 24351de688337..21a47a3d5f999 100755
--- a/lang/update_pot.sh
+++ b/lang/update_pot.sh
@@ -47,6 +47,8 @@ if ! lang/extract_json_strings.py \
         -X data/json/npcs/TALK_TEST.json \
         -X data/core/sentinels.json \
         -X data/raw/color_templates/no_bright_background.json \
+        -D data/mods/BlazeIndustries \
+        -D data/mods/desert_region \
         -n "$package $version" \
         -r lang/po/gui.pot \
         -o lang/po/json.pot