@@ -14,23 +14,30 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-    continue-on-error: true
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
-        
+
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: '3.11'
-          
+
       - name: Install sphinx-lint
         run: pip install sphinx-lint
-        
+
+      - name: Install gettext tools
+        run: sudo apt-get install -y gettext
+
       - name: Setup problem matcher
         uses: rffontenelle/sphinx-lint-problem-matcher@v1.0.0
-        
+
       - name: Run sphinx-lint
         run: sphinx-lint
+        continue-on-error: true
+
+      - name: Check PO file validity
+        run: find . -name '*.po' -exec msgfmt --check {} \;
+
+      - name: Check markup preservation
+        run: python3 scripts/check_markup.py .
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+scripts/check_markup.py
+
+Verify that Sphinx roles, inline literals, and format placeholders in the
+English msgid are preserved verbatim in the Persian msgstr. Catches the most
+common review slip: translating or mangling `:class:`int``-style markup,
+``code`` spans, %s/{0} placeholders, or |substitution| refs.
+
+Usage:
+    python3 scripts/check_markup.py library/functions.po
+    python3 scripts/check_markup.py tutorial/*.po
+    python3 scripts/check_markup.py .          # recurse a whole directory
+"""
+import re
+import sys
+from pathlib import Path
+
+PATTERNS = [
+    ("sphinx role", re.compile(r":[\w.-]+:`.*?`")),
+    ("literal/code span", re.compile(r"``.*?``")),
+    ("substitution ref", re.compile(r"\|[\w.-]+\|")),
+    ("percent placeholder", re.compile(r"%\(\w+\)[a-zA-Z]|%[a-zA-Z]")),
+    ("brace placeholder", re.compile(r"\{[^{}\s]*\}")),
+]
+
+
+def unescape(raw: str) -> str:
+    """Undo PO string escaping (raw includes the surrounding quotes)."""
+    inner = raw[1:-1]
+    out = []
+    i = 0
+    while i < len(inner):
+        c = inner[i]
+        if c == "\\" and i + 1 < len(inner):
+            nxt = inner[i + 1]
+            out.append({"n": "\n", "t": "\t", '"': '"', "\\": "\\"}.get(nxt, nxt))
+            i += 2
+        else:
+            out.append(c)
+            i += 1
+    return "".join(out)
+
+
+def parse_po(path: Path):
+    """Yield (location, flags, msgid, msgstr) for each entry in a .po file."""
+    lines = path.read_text(encoding="utf-8").splitlines()
+    i, n = 0, len(lines)
+
+    def read_block(keyword_line):
+        nonlocal i
+        parts = [unescape(keyword_line.split(" ", 1)[1].strip())]
+        i += 1
+        while i < n and lines[i].strip().startswith('"'):
+            parts.append(unescape(lines[i].strip()))
+            i += 1
+        return "".join(parts)
+
+    while i < n:
+        location, flags = "", []
+        while i < n and lines[i].startswith("#"):
+            if lines[i].startswith("#:"):
+                location = lines[i][2:].strip()
+            elif lines[i].startswith("#,"):
+                flags = [f.strip() for f in lines[i][2:].split(",")]
+            i += 1
+        if i >= n or not lines[i].startswith("msgid"):
+            i += 1
+            continue
+
+        msgid = read_block(lines[i])
+        msgid_plural = read_block(lines[i]) if i < n and lines[i].startswith("msgid_plural") else None
+
+        if i < n and lines[i].startswith("msgstr["):
+            msgstrs = {}
+            while i < n and lines[i].startswith("msgstr["):
+                idx = int(lines[i][7:lines[i].index("]")])
+                msgstrs[idx] = read_block(lines[i])
+            yield location, flags, msgid, msgstrs.get(0, "")
+            if msgid_plural is not None and 1 in msgstrs:
+                yield location, flags, msgid_plural, msgstrs[1]
+            continue
+
+        msgstr = read_block(lines[i]) if i < n and lines[i].startswith("msgstr") else ""
+        yield location, flags, msgid, msgstr
+
+
+def check_file(path: Path) -> int:
+    problems = 0
+    for location, flags, msgid, msgstr in parse_po(path):
+        if not msgid or not msgstr:
+            continue  # header entry or still untranslated
+        for label, pattern in PATTERNS:
+            expected = pattern.findall(msgid)
+            if not expected:
+                continue
+            missing = [tok for tok in expected if tok not in msgstr]
+            if missing:
+                problems += 1
+                loc = f" ({location})" if location else ""
+                tag = " [fuzzy]" if "fuzzy" in flags else ""
+                print(f"{path}{loc}{tag}: missing {label}: {missing}")
+                print(f"    msgid : {msgid[:100]}")
+                print(f"    msgstr: {msgstr[:100]}")
+    return problems
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    files = []
+    for arg in sys.argv[1:]:
+        p = Path(arg)
+        files.extend(sorted(p.rglob("*.po"))) if p.is_dir() else files.append(p)
+
+    total = sum(check_file(f) for f in files)
+
+    if total:
+        print(f"\n{total} markup mismatch(es) found.")
+        sys.exit(1)
+    print("No markup mismatches found.")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+scripts/update_python_version.py
+
+Sync this repo's .po files against a target CPython release tag.
+
+Usage:
+    python scripts/update_python_version.py v3.14.6
+    python scripts/update_python_version.py v3.15.0 --keep-src
+
+Run this from anywhere inside the repo (it locates the repo root from
+this file's location, assuming it lives in <repo>/scripts/).
+"""
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+WORKDIR = REPO_ROOT / ".cpython-src"  # scratch clone, deleted by default when done
+
+
+def run(cmd, cwd=None):
+    print(f"$ {' '.join(str(c) for c in cmd)}")
+    subprocess.run(cmd, cwd=cwd, check=True)
+
+
+def fetch_cpython(tag: str) -> None:
+    if WORKDIR.exists():
+        shutil.rmtree(WORKDIR)
+    run([
+        "git", "clone", "--depth", "1", "--branch", tag,
+        "https://github.com/python/cpython.git", str(WORKDIR),
+    ])
+
+
+def build_gettext(tag: str) -> Path:
+    """Build .pot templates from the CPython docs at `tag`, return their root dir."""
+    doc_dir = WORKDIR / "Doc"
+    venv_dir = doc_dir / "venv"
+    run([sys.executable, "-m", "venv", str(venv_dir)])
+    pip = venv_dir / "bin" / "pip"
+    sphinx_build = venv_dir / "bin" / "sphinx-build"
+    run([str(pip), "install", "-r", "requirements.txt"], cwd=doc_dir)
+    run([str(sphinx_build), "-b", "gettext", ".", "build/gettext"], cwd=doc_dir)
+    return doc_dir / "build" / "gettext"
+
+
+def merge_all(pot_root: Path) -> None:
+    updated = new_po = missing_pot = 0
+
+    # existing .po files -> merge against matching .pot by relative path
+    for po_path in sorted(REPO_ROOT.rglob("*.po")):
+        if ".cpython-src" in po_path.parts or ".git" in po_path.parts:
+            continue
+        rel = po_path.relative_to(REPO_ROOT)
+        pot_path = pot_root / rel.with_suffix(".pot")
+        if not pot_path.exists():
+            print(f"  ! no matching .pot for {rel} "
+                  f"(page may have been removed/renamed upstream — review manually)")
+            missing_pot += 1
+            continue
+        run(["msgmerge", "--update", "--backup=off", str(po_path), str(pot_path)])
+        updated += 1
+
+    # brand-new .pot files with no .po counterpart yet -> create empty .po via msginit
+    for pot_path in sorted(pot_root.rglob("*.pot")):
+        rel = pot_path.relative_to(pot_root)
+        po_path = REPO_ROOT / rel.with_suffix(".po")
+        if not po_path.exists():
+            po_path.parent.mkdir(parents=True, exist_ok=True)
+            run(["msginit", "--no-translator", "-l", "fa", "-i", str(pot_path), "-o", str(po_path)])
+            new_po += 1
+
+    print(f"\nSummary: {updated} .po files merged, {new_po} new .po files created, "
+          f"{missing_pot} .po files with no matching upstream source.")
+
+
+def check_po_files() -> None:
+    bad = []
+    for po_path in sorted(REPO_ROOT.rglob("*.po")):
+        if ".cpython-src" in po_path.parts or ".git" in po_path.parts:
+            continue
+        result = subprocess.run(
+            ["msgfmt", "--check", "-o", "/dev/null", str(po_path)],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            bad.append((po_path, result.stderr.strip()))
+
+    if bad:
+        print("\nBroken .po files (fix before committing):")
+        for path, err in bad:
+            print(f"  {path}:\n    {err}")
+        sys.exit(1)
+    print("\nAll .po files pass `msgfmt --check`.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("tag", help="CPython git tag to sync against, e.g. v3.14.6")
+    parser.add_argument("--keep-src", action="store_true",
+                         help="keep the scratch CPython checkout instead of deleting it")
+    args = parser.parse_args()
+
+    print(f"== Fetching CPython {args.tag} ==")
+    fetch_cpython(args.tag)
+
+    print("\n== Building gettext templates ==")
+    pot_root = build_gettext(args.tag)
+
+    print("\n== Merging into this repo's .po files ==")
+    merge_all(pot_root)
+
+    print("\n== Validating .po files ==")
+    check_po_files()
+
+    if not args.keep_src:
+        shutil.rmtree(WORKDIR, ignore_errors=True)
+
+    print(f"\nDone. Review the diff, then commit as something like:\n"
+          f'  git commit -am "Sync translations with CPython {args.tag}"')
+
+
+if __name__ == "__main__":
+    main()