Add fix_term_refs.py script

Author: sepehr-rs

scripts/fix_term_refs.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+fix_term_refs.py
+
+Converts plain Sphinx `:term:`English`` references inside the *translated*
+(msgstr) strings of a gettext .po file into the explicit-title form:
+
+    :term:`Persian translation <English>`
+
+so that the reader sees translated text while the link still resolves to the
+correct (English) glossary entry ID.
+
+The English msgid lines are left completely untouched. Only msgstr strings
+are modified, and only occurrences of :term:`X` where X has no `<...>`
+already (i.e. plain references, not ones that already specify a custom title).
+
+Persian translations are looked up in two places, in priority order:
+  1. This .po file's own entries — i.e. if somewhere in the file there's a
+     msgid "duck-typing" / msgstr "نوع‌دهی اردکی", that translation is used.
+  2. A fallback dictionary (FALLBACK_MAP below) for terms that aren't
+     separately defined in the .po file itself. Edit/extend this dict for
+     your own glossary as needed.
+
+If a term can't be resolved through either source, the reference is left
+unchanged and reported at the end so you can add it to FALLBACK_MAP or fix
+the source file.
+
+Usage:
+    python3 fix_term_refs.py input.po output.po
+
+If output.po is omitted, writes to input.fixed.po next to the input file.
+"""
+
+import re
+import sys
+
+# ---------------------------------------------------------------------------
+# Fallback English -> target-language translations, used only when a term
+# isn't itself defined as a msgid/msgstr pair inside the .po file.
+# Extend this for your own glossary/language as needed.
+# ---------------------------------------------------------------------------
+FALLBACK_MAP = {
+    "accessibility": "دسترسی‌پذیری", "await": "await", "argument": "آرگومان",
+    "async": "ناهمگام، غیرهمگام", "API": "API", "attribute": "ویژگی، صفت، شاخصه",
+    "boolean": "بولی", "built-in": "توکار، درونی، درون‌ساخته",
+    "callback": "کال‌بک، فراخوانی بازگشتی", "character": "نویسه",
+    "context management": "مدیریت زمینه", "class": "کلاس", "cache": "نهانگاه",
+    "coroutine": "هم‌روال", "command line": "خط فرمان", "community": "کامیونیتی",
+    "component": "کامپوننت", "custom": "سفارشی، اختصاصی",
+    "decorator": "دکوراتور، آراینده", "debugging": "اشکال‌زدایی، دیباگ کردن",
+    "decoding": "کدگشایی", "deprecated": "منسوخ، از رده خارج شده",
+    "dependency": "وابستگی", "dictionary": "دیکشنری", "directory": "پوشه",
+    "duck-typing": "نوع‌دهی اردکی", "DOM": "DOM", "element": "المان، عنصر",
+    "endpoint": "پایانه", "escape": "خنثی کردن", "encoding": "کدگذاری",
+    "ecosystem": "اکوسیستم", "event": "رویداد", "exception": "استثنا",
+    "expression": "عبارت", "function": "تابع", "f-string": "اف‌استرینگ",
+    "generator": "تولیدگر", "global": "سراسری", "garbage collection": "زباله‌روبی",
+    "generic function": "تابع عام، تابع عمومی", "hexadecimal": "مبنای شانزده",
+    "immortal": "نامیرا", "import": "ایمپورت", "immutable": "تغییرناپذیر",
+    "index": "اندیس، شماره", "instance": "نمونه", "integer": "عدد صحیح",
+    "interface": "رابط", "interpreter": "مفسر", "item": "آیتم",
+    "iterable": "تکرارپذیر", "keyword": "کلیدواژه",
+    "keyword argument": "آرگومان کلیدواژه‌ای", "list": "فهرست",
+    "list comprehension": "درک فهرستی", "load": "بارگذاری", "loader": "بارگذار",
+    "local": "محلی", "loop": "حلقه", "method": "متد", "metaclass": "فراکلاس",
+    "mock": "ماک", "module": "ماژول", "mutable": "تغییرپذیر",
+    "namespace": "نام‌فضا", "object": "شیء", "operator": "عملگر",
+    "package": "بسته", "parameter": "پارامتر", "positional": "جایگاهی",
+    "property": "ویژگی، پراپرتی، خصوصیت", "parallelism": "موازی‌سازی",
+    "quotation": "علامت نقل‌قول", "raise": "پرتاب", "return": "بازگشت، برگرداندن",
+    "runtime": "ران‌تایم", "race": "رقابت", "scope": "محدوده",
+    "shadowing": "پوشاندن", "stack traceback": "ردگیری پشته", "statement": "دستور",
+    "string": "رشته", "syntax": "سینتکس، نحو", "shell": "پوسته",
+    "syntactic sugar": "قند نحوی", "tracking": "پیگیری",
+    "type": "نوع، نوع داده، تایپ", "thread": "نخ", "unit test": "یونیت تست",
+    "unpacking": "واگشایی", "value": "مقدار", "variable": "متغیر",
+    "wrapper": "پوششی، دربرگیرنده", "iterator": "تکرارگر",
+}
+
+# Matches BOTH forms so both get (re)normalized to :term:`Persian <target>`:
+#   :term:`X`                -- plain ref, target/display are both X
+#   :term:`Something <X>`    -- already has explicit title (target is X);
+#                                "Something" may be stale English display
+#                                text left over from the source file.
+# Group 'target' is always the real glossary-entry id to link to.
+TERM_RE = re.compile(r':term:`(?:(?P<target_only>[^`<>]+)|[^`<>]*<(?P<target_bracketed>[^`<>]+)>)`')
+
+
+def po_unescape(s):
+    return s.replace('\\n', '\n').replace('\\"', '"').replace('\\\\', '\\')
+
+
+def po_escape(s):
+    return s.replace('\\', '\\\\').replace('"', '\\"').replace('\n', '\\n')
+
+
+def parse_po_string_block(lines, i, n):
+    """Parse a 'msgid "..."' or 'msgstr "..."' plus any continuation quoted
+    lines. Returns (keyword, parts, next_index)."""
+    m = re.match(r'^(msgid|msgstr)\s+"(.*)"\s*$', lines[i])
+    keyword = m.group(1)
+    parts = [m.group(2)]
+    j = i + 1
+    while j < n and re.match(r'^\s*"(.*)"\s*$', lines[j]):
+        parts.append(re.match(r'^\s*"(.*)"\s*$', lines[j]).group(1))
+        j += 1
+    return keyword, parts, j
+
+
+def parse_po(text):
+    """Parse .po text into a list of entries: pairs (msgid/msgstr) or other
+    raw lines (comments, headers, blanks), preserving order."""
+    lines = text.split("\n")
+    n = len(lines)
+    entries = []
+    i = 0
+    while i < n:
+        if re.match(r'^msgid\s+"', lines[i]):
+            _, id_parts, j1 = parse_po_string_block(lines, i, n)
+            if j1 < n and re.match(r'^msgstr\s+"', lines[j1]):
+                _, str_parts, j2 = parse_po_string_block(lines, j1, n)
+                entries.append({"type": "pair", "msgid_parts": id_parts,
+                                 "msgstr_parts": str_parts})
+                i = j2
+            else:
+                entries.append({"type": "other", "raw": [lines[i]]})
+                i = i + 1  # fall back to line-by-line if malformed
+        else:
+            entries.append({"type": "other", "raw": [lines[i]]})
+            i += 1
+    return entries
+
+
+def join_parts_decoded(parts):
+    return "".join(po_unescape(p) for p in parts)
+
+
+def build_term_map(entries):
+    """Build English-term -> translation dict from the .po file's own short,
+    markup-free msgid/msgstr pairs (these are glossary entry definitions)."""
+    term_map = {}
+    for e in entries:
+        if e["type"] != "pair":
+            continue
+        msgid_full = join_parts_decoded(e["msgid_parts"]).strip()
+        msgstr_full = join_parts_decoded(e["msgstr_parts"]).strip()
+        if not msgid_full or not msgstr_full:
+            continue
+        if re.search(r'[`:]', msgid_full) or len(msgid_full) > 60:
+            continue
+        term_map[msgid_full] = msgstr_full
+    return term_map
+
+
+def fix_po(text):
+    """Run the conversion. Returns (new_text, changed_count, missing_terms)."""
+    entries = parse_po(text)
+    term_map = build_term_map(entries)
+    missing = set()
+
+    def translate(term):
+        if term in term_map:
+            return term_map[term]
+        if term in FALLBACK_MAP:
+            return FALLBACK_MAP[term]
+        return None
+
+    def replace_in_text(s):
+        def repl(m):
+            term = m.group('target_only') or m.group('target_bracketed')
+            translated = translate(term)
+            if translated is None:
+                missing.add(term)
+                return m.group(0)  # leave completely unchanged
+            return f':term:`{translated} <{term}>`'
+        return TERM_RE.sub(repl, s)
+
+    changed_count = 0
+    for e in entries:
+        if e["type"] != "pair":
+            continue
+        msgstr_full = join_parts_decoded(e["msgstr_parts"])
+        if ':term:`' not in msgstr_full:
+            continue
+        new_full = replace_in_text(msgstr_full)
+        if new_full == msgstr_full:
+            continue
+        changed_count += 1
+        if len(e["msgstr_parts"]) > 1:
+            segs = new_full.split("\n")
+            new_parts = [""]
+            for k, seg in enumerate(segs):
+                suffix = "\\n" if k < len(segs) - 1 else ""
+                new_parts.append(po_escape(seg) + suffix)
+            e["msgstr_parts"] = new_parts
+        else:
+            e["msgstr_parts"] = [po_escape(new_full)]
+
+    out_lines = []
+    for e in entries:
+        if e["type"] == "other":
+            out_lines.extend(e["raw"])
+        else:
+            out_lines.append(f'msgid "{e["msgid_parts"][0]}"')
+            for p in e["msgid_parts"][1:]:
+                out_lines.append(f'"{p}"')
+            out_lines.append(f'msgstr "{e["msgstr_parts"][0]}"')
+            for p in e["msgstr_parts"][1:]:
+                out_lines.append(f'"{p}"')
+
+    return "\n".join(out_lines), changed_count, missing
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python3 fix_term_refs.py input.po [output.po]")
+        sys.exit(1)
+
+    in_path = sys.argv[1]
+    out_path = sys.argv[2] if len(sys.argv) > 2 else re.sub(
+        r'\.po$', '.fixed.po', in_path)
+
+    with open(in_path, encoding="utf-8") as f:
+        text = f.read()
+
+    new_text, changed_count, missing = fix_po(text)
+
+    with open(out_path, "w", encoding="utf-8") as f:
+        f.write(new_text)
+
+    print(f"Wrote: {out_path}")
+    print(f"Changed msgstr entries: {changed_count}")
+    if missing:
+        print(f"Terms left unchanged (no translation found, {len(missing)}):")
+        for t in sorted(missing):
+            print(f"  - {t}")
+    else:
+        print("All :term: references resolved.")
+
+
+if __name__ == "__main__":
+    main()