Add shared tooling scripts to 3.14 (po_status.py, check_roles.py, pre_push_check.sh, CLAUDE.md)

Author: sba72

CLAUDE.md

@@ -0,0 +1,50 @@
+# Übersetzungsregeln python-docs-de 
+
+## Sprache
+- Konsequent "Du"-Form
+- msgid (Englisch) NIE verändern, nur msgstr bearbeiten
+
+## Sphinx/reST-Syntax
+- `:ref:`Anzeigetext <ziel>`` → nur Anzeigetext übersetzen, Ziel bleibt Englisch
+- `:class:`/:func:`/:meth:`/:attr:`/:mod:`/:exc:`/:const:`/:keyword:`/:program:`/:pep:`/:kbd:`X`` ohne <...> → X bleibt unverändert
+- `~`-Präfix (z.B. `:meth:`~object.__lt__``) → kompletter Ausdruck inkl. ~ unverändert
+- `!`-Präfix (z.B. `:mod:`!string``) → nur Verlinkung unterdrückt, Bezeichner unverändert
+- Backticks sauber schließen, kein Leerzeichen davor
+- `::` am Satzende (leitet Codeblock ein) bleibt stehen
+- Zitierte Originaltitel aus externen Standards (z.B. Unicode Standard "Default Case Folding") bleiben unübersetzt in Anführungszeichen
+- Platzhalter/Makros (%s, {0}, <TRANSLATION_REPO_>) unverändert
+
+## Code-/REPL-Beispiele
+- Reiner Code, Ausgaben, Tracebacks: unverändert
+- NUR `#`-Kommentare darin übersetzen
+- msgstr immer identisch zu msgid befüllen, NIE leer lassen (auch bei reinem Code)
+
+## Fuzzy-Flags
+- Nach Prüfung/Übersetzung entfernen
+- Datei-Header-fuzzy (über leerem msgid "") ist reine Altlast, ohne Prüfung löschbar
+
+## Terminologie (unübersetzt lassen)
+Dictionary, Tuple, List Comprehension, Sentinel, Lazy Import, Property,
+Slice, Type Hints, f-string/f-String, t-string/T-String, Whitespace (Singular),
+Subclassing, API, Repository, Wheel
+
+## Terminologie (feste Übersetzung)
+- frozen... → unveränderlich (NICHT "eingefroren")
+- picklable → picklebar
+- I/O (NICHT E/A)
+- locale → Ländereinstellung
+- presentation type → Darstellungstyp
+- String (als Datentyp) → Zeichenkette
+- Debug/Conversion/Format specifier → Debug-/Konvertierungs-/Formatbezeichner
+- rich comparisons → erweiterte Vergleichsoperationen
+- generic over → "Typparameter" bei mehreren festen Parametern (z.B. dict: zwei),
+  "hinsichtlich des Typs" bei genau einem Parameter (list/set/frozenset/memoryview),
+  Plural "Typen" bei variabler Anzahl (tuple)
+
+## PO-Datei-Struktur
+- Genau ein leerer msgid ""-Header mit charset=UTF-8 pro Datei
+- Zeilenlänge ~80 Zeichen (powrap via CI erledigt das automatisch bei Push)
+- Vor Push immer lokal prüfen: find . -name "*.po" -not -path "./c-api/*" -exec msgfmt --check {} -o /dev/null \;
+
+## Core-Dateien (Pflicht für Sprachschalter-Aufnahme)
+Nur: bugs.po, library/functions.po, tutorial/*.po

check_roles.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+check_roles.py — Vergleicht Sphinx-Rollen (:ref:, :term:, :class:, :func:, ...)
+zwischen msgid und msgstr in .po-Dateien, um Inkonsistenzen zu finden, OHNE
+dass ein kompletter Sphinx-Build nötig ist. Erkennt dieselbe Fehlerklasse wie
+Sphinxs 'i18n.inconsistent_references', plus zusätzliche Muster
+(fehlende/überzählige Rollen, falsche Ziele).
+"""
+import re
+import sys
+from pathlib import Path
+
+ROLE_RE = re.compile(r":([a-zA-Z][\w-]*):`([^`]+)`")
+
+
+def normalize_target(content: str) -> str:
+    content = content.strip()
+    m = re.match(r"^(.*)<([^<>]+)>$", content)
+    if m:
+        return m.group(2).strip()
+    return content
+
+
+ROLES_WITHOUT_FIXED_TARGET = {"dfn"}
+
+
+def extract_roles(text: str) -> list[tuple[str, str]]:
+    roles = []
+    for role, content in ROLE_RE.findall(text):
+        if role in ROLES_WITHOUT_FIXED_TARGET:
+            continue
+        roles.append((role, normalize_target(content)))
+    return sorted(roles)
+
+
+def parse_po_entries(path: Path):
+    lines = path.read_text(encoding="utf-8", errors="replace").split("\n")
+    i = 0
+    entries = []
+    while i < len(lines):
+        line = lines[i]
+        if line.startswith("#~"):
+            i += 1
+            continue
+        is_fuzzy = False
+        while i < len(lines) and lines[i].startswith("#"):
+            if ", fuzzy" in lines[i]:
+                is_fuzzy = True
+            i += 1
+        if i >= len(lines) or not lines[i].startswith("msgid"):
+            i += 1
+            continue
+        msgid_lineno = i + 1
+        msgid_parts = []
+        m = re.match(r'msgid\s+"(.*)"$', lines[i])
+        if m:
+            msgid_parts.append(m.group(1))
+        i += 1
+        while i < len(lines) and lines[i].startswith('"'):
+            msgid_parts.append(lines[i].strip()[1:-1])
+            i += 1
+        if i >= len(lines) or not lines[i].startswith("msgstr"):
+            continue
+        msgstr_parts = []
+        m = re.match(r'msgstr\s+"(.*)"$', lines[i])
+        if m:
+            msgstr_parts.append(m.group(1))
+        i += 1
+        while i < len(lines) and lines[i].startswith('"'):
+            msgstr_parts.append(lines[i].strip()[1:-1])
+            i += 1
+        msgid = "".join(msgid_parts)
+        msgstr = "".join(msgstr_parts)
+        entries.append((msgid_lineno, msgid, msgstr, is_fuzzy))
+    return entries
+
+
+def check_file(path: Path) -> list[str]:
+    findings = []
+    try:
+        entries = parse_po_entries(path)
+    except Exception as e:
+        return [f"  [Parse-Fehler] {e}"]
+
+    for lineno, msgid, msgstr, is_fuzzy in entries:
+        if is_fuzzy or not msgstr or not msgid:
+            continue
+        orig_roles = extract_roles(msgid)
+        trans_roles = extract_roles(msgstr)
+        if orig_roles != trans_roles:
+            missing = [r for r in orig_roles if r not in trans_roles]
+            extra = [r for r in trans_roles if r not in orig_roles]
+            parts = []
+            if missing:
+                parts.append(f"fehlt: {missing}")
+            if extra:
+                parts.append(f"zusätzlich/falsch: {extra}")
+            findings.append(f"  Zeile ~{lineno}: {', '.join(parts)}")
+    return findings
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Nutzung: check_roles.py <verzeichnis-oder-datei> [--exclude dir1,dir2]")
+        sys.exit(1)
+
+    root = Path(sys.argv[1])
+    excludes = set()
+    if "--exclude" in sys.argv:
+        idx = sys.argv.index("--exclude")
+        excludes = set(sys.argv[idx + 1].split(","))
+
+    if root.is_file():
+        po_files = [root]
+    else:
+        po_files = sorted(
+            p for p in root.rglob("*.po")
+            if not excludes.intersection(p.relative_to(root).parts)
+        )
+
+    total_findings = 0
+    files_with_findings = 0
+    for po_file in po_files:
+        findings = check_file(po_file)
+        if findings:
+            files_with_findings += 1
+            total_findings += len(findings)
+            rel = po_file.relative_to(root) if root.is_dir() else po_file
+            print(f"\n{rel}")
+            for f in findings:
+                print(f)
+
+    print(f"\n{'=' * 60}")
+    print(f"{total_findings} mögliche Rollen-Inkonsistenz(en) in {files_with_findings} "
+          f"von {len(po_files)} Dateien gefunden.")
+    print("Hinweis: Das ist eine Heuristik (Textvergleich, kein echter Sphinx-Build) "
+          "-> bitte jeden Fund manuell gegenprüfen, es können auch Fehlalarme dabei sein.")
+    sys.exit(1 if total_findings else 0)
+
+
+if __name__ == "__main__":
+    main()

po_status.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+po_status.py — Listet alle .po-Dateien in einem Verzeichnisbaum mit
+Übersetzungsstand (x/y), Prozent, Dateigröße und Pfad und Status Gesamtübersetzung.
+"""
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+STATS_RE = re.compile(
+    r"(?:(\d+) translated messages?)?"
+    r"(?:, (\d+) fuzzy translations?)?"
+    r"(?:, (\d+) untranslated messages?)?"
+)
+
+
+def get_stats(po_file: Path):
+    """Ruft msgfmt --statistics auf und parst das Ergebnis."""
+    try:
+        result = subprocess.run(
+            ["msgfmt", "--statistics", "-o", "/dev/null", str(po_file)],
+            capture_output=True, text=True, timeout=15,
+        )
+    except FileNotFoundError:
+        sys.exit("Fehler: 'msgfmt' wurde nicht gefunden. Ist gettext installiert "
+                 "(z.B. 'brew install gettext' + PATH-Anpassung)?")
+
+    output = (result.stderr or "") + (result.stdout or "")
+    if "error" in output.lower() and "translated" not in output.lower():
+        return None  # Syntaxfehler in der Datei
+
+    m = STATS_RE.search(output)
+    if not m:
+        return {"translated": 0, "fuzzy": 0, "untranslated": 0}
+    translated, fuzzy, untranslated = (int(x) if x else 0 for x in m.groups())
+    return {"translated": translated, "fuzzy": fuzzy, "untranslated": untranslated}
+
+
+def human_size(num_bytes: int) -> str:
+    for unit in ("B", "KB", "MB"):
+        if num_bytes < 1024:
+            return f"{num_bytes:.0f} {unit}" if unit == "B" else f"{num_bytes:.1f} {unit}"
+        num_bytes /= 1024
+    return f"{num_bytes:.1f} GB"
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("path", nargs="?", default=".", help="Wurzelverzeichnis (Standard: .)")
+    parser.add_argument("--exclude", default="c-api,.venv,.git",
+                         help="Kommagetrennte Ordnernamen, die übersprungen werden")
+    parser.add_argument("--sort", choices=["path", "percent", "size"], default="percent")
+    parser.add_argument("--max-percent", type=float, default=100.1,
+                         help="Nur Dateien mit weniger als diesem Prozentwert anzeigen")
+    args = parser.parse_args()
+
+    root = Path(args.path).resolve()
+    excludes = {e.strip() for e in args.exclude.split(",") if e.strip()}
+
+    po_files = sorted(
+        p for p in root.rglob("*.po")
+        if not excludes.intersection(p.relative_to(root).parts)
+    )
+
+    if not po_files:
+        print(f"Keine .po-Dateien unter {root} gefunden.")
+        return
+
+    rows = []
+    for po_file in po_files:
+        stats = get_stats(po_file)
+        rel_path = po_file.relative_to(root)
+        size = po_file.stat().st_size
+        if stats is None:
+            rows.append((str(rel_path), "FEHLER (Syntax)", -1.0, size))
+            continue
+        total = stats["translated"] + stats["fuzzy"] + stats["untranslated"]
+        pct = (stats["translated"] / total * 100) if total else 100.0
+        label = f"{stats['translated']}/{total}"
+        if stats["fuzzy"]:
+            label += f" ({stats['fuzzy']} fuzzy)"
+        rows.append((str(rel_path), label, pct, size))
+
+    # Gesamtstatistik wird VOR dem --max-percent-Filter berechnet (über alle Dateien)
+    complete_count = sum(1 for r in rows if r[2] >= 100.0)
+    error_count = sum(1 for r in rows if r[2] < 0)
+    total_translated = sum(int(r[1].split("/")[0]) for r in rows if r[2] >= 0)
+    total_strings = sum(int(r[1].split("/")[1].split(" ")[0]) for r in rows if r[2] >= 0)
+    overall_pct = (total_translated / total_strings * 100) if total_strings else 0.0
+
+    rows = [r for r in rows if r[2] < args.max_percent or r[2] < 0]
+
+    if not rows:
+        print(f"Alle {len(po_files)} Dateien liegen bei/über --max-percent {args.max_percent} "
+              f"— nichts anzuzeigen.")
+        return
+
+    if args.sort == "percent":
+        rows.sort(key=lambda r: r[2], reverse=True)  # 100% -> 0%
+    elif args.sort == "size":
+        rows.sort(key=lambda r: -r[3])
+
+    path_w = max(len(r[0]) for r in rows) + 2
+    label_w = max(len(r[1]) for r in rows) + 2
+
+    print(f"{'Pfad':<{path_w}}{'Übersetzt':<{label_w}}{'%':>7}   {'Größe':>8}")
+    print("-" * (path_w + label_w + 20))
+    for rel_path, label, pct, size in rows:
+        pct_str = "  n/a" if pct < 0 else f"{pct:6.1f}%"
+        print(f"{rel_path:<{path_w}}{label:<{label_w}}{pct_str:>7}   {human_size(size):>8}")
+
+    print("-" * (path_w + label_w + 20))
+    print(f"{len(rows)} von {len(po_files)} Dateien angezeigt "
+          f"(Filter: --max-percent {args.max_percent})")
+    print()
+    print(f"Vollständig übersetzt (100%): {complete_count} von {len(po_files)} Dateien")
+    if error_count:
+        print(f"Dateien mit Syntaxfehler:      {error_count}")
+    print(f"Gesamtstand über alle Dateien:  {total_translated}/{total_strings} Strings "
+          f"({overall_pct:.2f}%)")
+
+
+if __name__ == "__main__":
+    main()