@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/localization-reuse-map/scripts/fetch-annotations.py

@@ -1,37 +1,11 @@
 #!/usr/bin/env python3
-"""Fetch the content team's Final UX Writing annotations off the screen's Figma nodes.
-
-The CMS / content team writes the **final bilingual copy** as Figma Dev Mode
-annotations (category "Final UX Writing") directly on the text nodes, in the form
-`TR: <türkçe>\nEN: <english>`. The design text itself is usually a *placeholder*
-("Giriniz", "Lorem ipsum", "Ahmet Abdullah"), so the annotation  -  not the design
-text  -  is the content team's *actual* value. This script harvests them so the map
-can show an `İçerik (CMS)` column beside the new (resources) and legacy values.
-
-Three sources, in priority order (Figma changes constantly → live is primary):
-  1. REST  -  `GET https://api.figma.com/v1/files/<key>/nodes?ids=...`, header
-            `X-Figma-Token` (from --token, env FIGMA_ACCESS_TOKEN/FIGMA_TOKEN, or
-            the macOS keychain item `FIGMA_ACCESS_TOKEN`). Default.
-  2. MCP  -  `--from-mcp <raw.json>`: an already-captured Dev Mode dump (the host's
-            Figma plugin/`use_figma` output). No network, no rate limit  -  use it
-            for big runs or when REST is 429-throttled.
-  3. local  -  `--local <design-export-screen-dir>`: best-effort read of the in-repo
-            snapshot's `tree.json` (only if it carries `annotations`). The safety
-            net when neither API nor MCP is reachable; usually yields nothing, in
-            which case the CMS column is simply left blank (blank beats a guess).
-
-Why a script: parsing `TR:/EN:` labels out of a node tree across many nodes is
-pure IO + string work  -  slow and error-prone by hand. Read-only; touches no repo.
-
-Emits the `_annotations.json` contract (to --out or stdout):
-  { generatedAt, source, files[], auditedNodes[], count, withTr, withEn,
-    annotations: [ {nodeId, name, type, designText, raw, tr, en, mode} ] }
-
-The label→{tr,en} parser (`split_lang`) is a faithful port of the web skill's
-`lib/split-lang.mjs`, so iOS/Android and web stay byte-compatible on the rules.
+"""Gather the "Final UX Writing" Dev Mode annotations of a Figma screen into _annotations.json.
+
+The REST API is tried first; a saved MCP dump (--from-mcp) or the tree.json of
+a design export kept in the repo (--local) can stand in for it. The TR and EN
+copy of each annotation is separated. Nothing is written back to Figma.
 """
 import argparse
-import datetime
 import json
 import os
 import re
@@ -41,303 +15,268 @@ import sys
 import urllib.error
 import urllib.parse
 import urllib.request
+from datetime import datetime, timezone
 
-FIGMA_API = "https://api.figma.com/v1"
-CHUNK = 4  # Figma /nodes batches; mirrors the web extractor
-
-# --- label → {tr, en, mode}  -  verbatim port of lib/split-lang.mjs ----------
-# Annotation authors separate label from value with a colon, a hyphen, or the
-# en-dash their editor auto-inserts. Built from the codepoint so this file
-# carries no literal dash variant of its own.
-_DASHES = ':\\-' + chr(0x2013)
-RE_TR = re.compile(rf"^(?:tr|tr[kc]e|t[üu]rk[çc]e)\s*[{_DASHES}]\s*(.+)$", re.I)
-RE_EN = re.compile(rf"^(?:en|eng|ing|[iİ]ngilizce)\s*[{_DASHES}]\s*(.+)$", re.I)
-
-
-def split_lang(raw):
-    """Parse a Dev Mode annotation label into {tr, en, mode}.
-
-    Prefixed `TR:`/`EN:` lines win over position; otherwise line1=TR, line2=EN.
-    """
-    if not raw:
-        return {"tr": None, "en": None, "mode": "empty"}
-    lines = [ln.strip() for ln in re.split(r"\r?\n", raw)]
-    lines = [ln for ln in lines if ln]
-    tr = en = None
-    bare = []
-    for ln in lines:
-        m = RE_TR.match(ln)
-        if m and tr is None:
-            tr = m.group(1).strip()
-            continue
-        m = RE_EN.match(ln)
-        if m and en is None:
-            en = m.group(1).strip()
-            continue
-        bare.append(ln)
-    if tr is not None or en is not None:
-        bi = 0
-        if tr is None and bi < len(bare):
-            tr = bare[bi]
-            bi += 1
-        if en is None and bi < len(bare):
-            en = bare[bi]
-            bi += 1
-        return {"tr": tr, "en": en, "mode": "prefixed"}
-    if len(bare) >= 2:
-        return {"tr": bare[0], "en": bare[1], "mode": "two-line"}
-    if len(bare) == 1:
-        return {"tr": bare[0], "en": None, "mode": "single"}
-    return {"tr": None, "en": None, "mode": "empty"}
-
-
-def canon_id(s):
-    """`1234-56` (URL form) → `1234:56` (node-id form); trims."""
-    return re.sub(r"^(\d+)-(\d+)$", r"\1:\2", (s or "").strip())
-
-
-# --- annotation parsing ----------------------------------------------------
-def labels_of(node):
-    """The annotation label strings on a node (each `label` ?? `labelMarkdown`)."""
-    anns = node.get("annotations")
-    if not isinstance(anns, list):
-        return []
-    out = []
-    for a in anns:
-        if not isinstance(a, dict):
-            continue
-        lbl = a.get("label") or a.get("labelMarkdown") or ""
-        if lbl:
-            out.append(lbl)
-    return out
-
-
-def design_text(node):
-    if node.get("type") == "TEXT" and isinstance(node.get("characters"), str):
-        return node["characters"]
-    return node.get("name")
-
-
-def parse_item(node_id, name, ntype, dtext, labels):
-    """Run split_lang over each label; keep the first that yields tr or en."""
-    best = {"tr": None, "en": None, "mode": "empty"}
-    raw = ""
-    for lbl in (labels or []):
-        parsed = split_lang(lbl)
-        if parsed["tr"] is not None or parsed["en"] is not None:
-            best = parsed
-            raw = lbl
-            break
-        if not raw:
-            raw = lbl
+API = "https://api.figma.com/v1"
+BATCH = 4
+SEP = "[:\\-\u2013]"
+TR_RE = re.compile("^(?:tr|tr[kc]e|t[\u00fcu]rk[\u00e7c]e)\\s*" + SEP + "\\s*(.+)$", re.IGNORECASE)
+EN_RE = re.compile("^(?:en|eng|ing|[i\u0130]ngilizce)\\s*" + SEP + "\\s*(.+)$", re.IGNORECASE)
+
+
+def canon_id(node_id):
+    return str(node_id).strip().replace("-", ":")
+
+
+def split_lang(text):
+    picked = {"tr": None, "en": None}
+    loose = []
+    for line in filter(None, (piece.strip() for piece in str(text or "").splitlines())):
+        tr_hit, en_hit = TR_RE.match(line), EN_RE.match(line)
+        if tr_hit and picked["tr"] is None:
+            picked["tr"] = tr_hit.group(1).strip()
+        elif en_hit and picked["en"] is None:
+            picked["en"] = en_hit.group(1).strip()
+        else:
+            loose.append(line)
+    if picked["tr"] is None and picked["en"] is None:
+        padded = loose + [None, None]
+        style = {0: "empty", 1: "single"}.get(len(loose), "two-line")
+        return {"tr": padded[0], "en": padded[1], "mode": style}
+    spare = iter(loose)
+    for lang in ("tr", "en"):
+        if picked[lang] is None:
+            picked[lang] = next(spare, None)
+    return dict(picked, mode="prefixed")
+
+
+def label_text(annotation):
+    if isinstance(annotation, dict):
+        return annotation.get("label") or annotation.get("labelMarkdown") or ""
+    return str(annotation or "")
+
+
+def pick_label(labels):
+    for label in labels:
+        parsed = split_lang(label)
+        if parsed["tr"] or parsed["en"]:
+            return label, parsed
+    first = labels[0] if labels else ""
+    return first, split_lang(first)
+
+
+def record(node_id, name, node_type, design_text, labels):
+    raw, parsed = pick_label(labels)
     return {
-        "nodeId": node_id,
+        "nodeId": canon_id(node_id),
         "name": name,
-        "type": ntype,
-        "designText": dtext,
+        "type": node_type,
+        "designText": design_text,
         "raw": raw,
-        "tr": best["tr"],
-        "en": best["en"],
-        "mode": best["mode"],
+        "tr": parsed["tr"],
+        "en": parsed["en"],
+        "mode": parsed["mode"],
     }
 
 
-def walk_collect(node, out):
-    """Recurse a Figma node tree, collecting every node that carries annotations."""
-    labels = labels_of(node)
-    if labels:
-        out.append(parse_item(node.get("id"), node.get("name"),
-                              node.get("type"), design_text(node), labels))
-    for child in node.get("children", []) or []:
-        walk_collect(child, out)
-
-
-# --- sources ---------------------------------------------------------------
-def figma_token(args):
-    if args.token:
-        return args.token
-    for env in ("FIGMA_ACCESS_TOKEN", "FIGMA_TOKEN"):
-        v = os.environ.get(env)
-        if v:
-            return v.strip()
+def walk_nodes(root):
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        if not isinstance(node, dict):
+            continue
+        yield node
+        stack.extend(reversed(node.get("children") or []))
+
+
+def annotated(root):
+    found = []
+    for node in walk_nodes(root):
+        notes = node.get("annotations")
+        if isinstance(notes, list) and notes:
+            node_type = node.get("type")
+            design = node.get("characters") if node_type == "TEXT" else node.get("name")
+            node_id = node.get("id") or node.get("nodeId")
+            found.append(record(node_id, node.get("name"), node_type, design, [label_text(a) for a in notes]))
+    return found
+
+
+def keychain_secret(service):
     try:
-        r = subprocess.run(
-            ["security", "find-generic-password", "-s", "FIGMA_ACCESS_TOKEN", "-w"],
-            capture_output=True, text=True)
-        if r.returncode == 0 and r.stdout.strip():
-            return r.stdout.strip()
-    except Exception:
-        pass
-    return None
-
-
-def http_get_json(url, headers, ca_file):
-    ctx = ssl.create_default_context(cafile=ca_file) if ca_file else ssl.create_default_context()
-    req = urllib.request.Request(url, headers=headers)
+        lookup = subprocess.run(
+            ["security", "find-generic-password", "-s", service, "-w"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    secret = lookup.stdout.strip()
+    return secret if lookup.returncode == 0 and secret else None
+
+
+def figma_token(explicit):
+    if explicit:
+        return explicit
+    from_env = next((os.environ[v] for v in ("FIGMA_ACCESS_TOKEN", "FIGMA_TOKEN") if os.environ.get(v)), None)
+    return from_env or keychain_secret("FIGMA_ACCESS_TOKEN")
+
+
+def get_json(url, token, ca_file, timeout=60):
+    tls = ssl.create_default_context(cafile=ca_file) if ca_file else None
+    call = urllib.request.Request(url, headers={"X-Figma-Token": token})
     try:
-        with urllib.request.urlopen(req, context=ctx, timeout=60) as r:
-            return json.load(r)
-    except urllib.error.HTTPError as e:
-        if e.code == 429:
-            sys.exit("Figma 429 (rate-limited)  -  re-run with the MCP dump instead: "
-                     "--from-mcp <raw.json>.")
-        body = e.read()[:200]
-        sys.exit(f"Figma HTTP {e.code} for {url}: {body!r}")
-    except urllib.error.URLError as e:
-        msg = str(getattr(e, "reason", e))
-        if re.search(r"CERTIFICATE|ISSUER|SELF.SIGNED|UNABLE_TO|CERT", msg, re.I):
+        with urllib.request.urlopen(call, timeout=timeout, context=tls) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        if exc.code == 429:
+            sys.exit("Figma is rate limiting (HTTP 429). Dump the annotations with Figma MCP instead and pass that file via --from-mcp <raw.json>.")
+        snippet = exc.read()[:200].decode("utf-8", "replace")
+        sys.exit(f"Figma HTTP {exc.code} for {url}: {snippet}")
+    except urllib.error.URLError as exc:
+        why = str(exc.reason)
+        if any(marker in why.upper() for marker in ("CERTIFICATE", "SSL")):
             sys.exit(
-                "TLS verification failed. Behind a corporate proxy, export the system "
-                "roots and pass --ca-file:\n"
-                "  security find-certificate -a -p /System/Library/Keychains/"
-                "SystemRootCertificates.keychain > /tmp/ca.pem\n"
-                "  security find-certificate -a -p /Library/Keychains/System.keychain "
-                ">> /tmp/ca.pem\n"
-                "  ... --ca-file /tmp/ca.pem")
-        sys.exit(f"Figma request failed: {msg}")
+                "Could not verify TLS, most likely because a proxy signs traffic with its own root. "
+                "Write the system roots out with `security find-certificate -a -p > roots.pem` and add --ca-file roots.pem."
+            )
+        sys.exit(f"Could not reach Figma: {why}")
 
 
 def from_rest(file_key, node_ids, token, ca_file):
-    if not token:
-        sys.exit("No Figma token  -  pass --token, set FIGMA_ACCESS_TOKEN, or add the "
-                 "keychain item FIGMA_ACCESS_TOKEN (or use --from-mcp / --local).")
-    headers = {"X-Figma-Token": token}
-    collected = []
-    ids = [canon_id(n) for n in node_ids]
-    for i in range(0, len(ids), CHUNK):
-        batch = ids[i:i + CHUNK]
-        q = ",".join(urllib.parse.quote(n, safe="") for n in batch)
-        data = http_get_json(f"{FIGMA_API}/files/{file_key}/nodes?ids={q}", headers, ca_file)
-        for nid in batch:
-            entry = (data.get("nodes") or {}).get(nid)
-            doc = entry.get("document") if isinstance(entry, dict) else None
-            if doc:
-                walk_collect(doc, collected)
-    return collected, "rest"
+    wanted = list(map(canon_id, node_ids))
+    found = []
+    for offset in range(0, len(wanted), BATCH):
+        chunk = wanted[offset:offset + BATCH]
+        joined = urllib.parse.quote(",".join(chunk), safe="")
+        reply = get_json(f"{API}/files/{file_key}/nodes?ids={joined}", token, ca_file)
+        by_id = reply.get("nodes") or {}
+        for node_id in chunk:
+            document = (by_id.get(node_id) or {}).get("document")
+            if document:
+                found.extend(annotated(document))
+    return found, [file_key], wanted
+
+
+def read_json(path):
+    with open(path, encoding="utf-8") as stream:
+        return json.load(stream)
 
 
 def from_mcp(path):
-    with open(path, encoding="utf-8") as fh:
-        dump = json.load(fh)
-    items = dump if isinstance(dump, list) else (dump.get("annotations") or dump.get("items") or [])
-    collected = []
-    files = []
-    for it in items:
-        fk = it.get("fileKey")
-        if fk and fk not in files:
-            files.append(fk)
-        labels = it.get("labels")
-        if labels is None and it.get("raw") is not None:
-            labels = [it["raw"]]
-        collected.append(parse_item(it.get("nodeId"), it.get("name"), it.get("type"),
-                                    it.get("designText"), labels or []))
-    return collected, "mcp", files
-
-
-def from_local(screen_dir):
-    """Best-effort: read annotations from a design-export tree.json if it has any."""
-    tree = os.path.join(screen_dir, "tree.json")
+    data = read_json(path)
+    if isinstance(data, dict):
+        items = data.get("annotations") or data.get("items") or []
+    else:
+        items = data
+    found, files, audited = [], [], []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        labels = item.get("labels")
+        if not isinstance(labels, list):
+            labels = [item.get("raw")] if item.get("raw") else []
+        found.append(record(item.get("nodeId"), item.get("name"), item.get("type"), item.get("designText"), [label_text(l) for l in labels]))
+        if item.get("fileKey") and item["fileKey"] not in files:
+            files.append(item["fileKey"])
+        if item.get("nodeId"):
+            audited.append(canon_id(item["nodeId"]))
+    return found, files, audited
+
+
+def from_local(directory):
+    tree = os.path.join(directory, "tree.json")
     if not os.path.isfile(tree):
-        return [], "local"
-    with open(tree, encoding="utf-8") as fh:
-        data = json.load(fh)
-    roots = data if isinstance(data, list) else [data]
-    collected = []
-    for root in roots:
-        if isinstance(root, dict):
-            walk_collect(root, collected)
-    return collected, "local"
+        return [], [], []
+    data = read_json(tree)
+    frames = [data] if not isinstance(data, list) else data
+    found = [item for frame in frames for item in annotated(frame)]
+    ids = [frame.get("nodeId") or frame.get("id") for frame in frames if isinstance(frame, dict)]
+    return found, [], [canon_id(i) for i in ids if i]
+
+
+def pick_source(opts, cli, file_key, nodes):
+    if opts.from_mcp or opts.source == "mcp":
+        if not opts.from_mcp:
+            cli.error("--source mcp needs --from-mcp <raw.json>")
+        return ("mcp",) + from_mcp(opts.from_mcp)
+    if opts.source == "local":
+        if not opts.local:
+            cli.error("--source local needs --local <design-export-screen-dir>")
+        return ("local",) + from_local(opts.local)
+    have_target = bool(file_key and nodes)
+    if opts.source == "rest":
+        if not have_target:
+            cli.error("--source rest needs a file key and node-ids (--file/--nodes or --mapping)")
+        token = figma_token(opts.token)
+        if not token:
+            sys.exit("No Figma token found. Export FIGMA_ACCESS_TOKEN or FIGMA_TOKEN, keep it in the keychain under FIGMA_ACCESS_TOKEN, or use --token.")
+        return ("rest",) + from_rest(file_key, nodes, token, opts.ca_file)
+    token = figma_token(opts.token) if have_target else None
+    if have_target and token:
+        try:
+            return ("rest",) + from_rest(file_key, nodes, token, opts.ca_file)
+        except SystemExit as exc:
+            if not opts.local:
+                raise
+            print(f"# REST fetch did not work ({exc}); using --local instead", file=sys.stderr)
+            return ("local",) + from_local(opts.local)
+    if opts.local:
+        return ("local",) + from_local(opts.local)
+    cli.error("nothing to do: give --file/--nodes (or --mapping) with a token, --from-mcp, or --local")
 
 
 def main():
-    ap = argparse.ArgumentParser(description=__doc__,
-                                 formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--file", help="Figma fileKey (REST)")
-    ap.add_argument("--nodes", help="comma-separated node-ids (REST), e.g. '10065:56313,10065:56329'")
-    ap.add_argument("--mapping", help="a mapping JSON to read figmaFileKey + figmaNodes from")
-    ap.add_argument("--from-mcp", dest="from_mcp", help="captured Dev Mode dump (MCP path)")
-    ap.add_argument("--local", help="design-export screen dir (fallback; reads tree.json)")
-    ap.add_argument("--source", choices=["auto", "rest", "mcp", "local"], default="auto",
-                    help="force a source; 'auto' tries REST then --local (default)")
-    ap.add_argument("--token", help="Figma token (else env / keychain)")
-    ap.add_argument("--ca-file", help="CA bundle for TLS behind a corporate proxy")
-    ap.add_argument("--out", help="write _annotations.json here (default: stdout)")
-    args = ap.parse_args()
-
-    file_key = args.file
-    node_ids = [n.strip() for n in (args.nodes or "").split(",") if n.strip()]
-    if args.mapping:
-        with open(args.mapping, encoding="utf-8") as fh:
-            m = json.load(fh)
-        file_key = file_key or m.get("figmaFileKey")
-        if not node_ids:
-            node_ids = [str(n) for n in (m.get("figmaNodes") or [])]
-
-    files = [file_key] if file_key else []
-    source = args.source
-
-    if args.from_mcp or source == "mcp":
-        if not args.from_mcp:
-            ap.error("--source mcp needs --from-mcp <raw.json>")
-        collected, source, mcp_files = from_mcp(args.from_mcp)
-        files = mcp_files or files
-    elif source == "local":
-        if not args.local:
-            ap.error("--source local needs --local <dir>")
-        collected, source = from_local(args.local)
-    elif source == "rest":
-        if not (file_key and node_ids):
-            ap.error("REST needs --file and --nodes (or --mapping)")
-        collected, source = from_rest(file_key, node_ids, figma_token(args), args.ca_file)
-    else:  # auto: REST first, fall back to --local
-        if file_key and node_ids and figma_token(args):
-            try:
-                collected, source = from_rest(file_key, node_ids, figma_token(args), args.ca_file)
-            except SystemExit:
-                if not args.local:
-                    raise
-                sys.stderr.write("# REST failed  -  falling back to --local\n")
-                collected, source = from_local(args.local)
-        elif args.local:
-            collected, source = from_local(args.local)
-        else:
-            ap.error("nothing to do  -  supply --file/--nodes (or --mapping) for REST, "
-                     "--from-mcp for MCP, or --local for the snapshot fallback")
-
-    # de-dup by nodeId, keep first (REST returns each requested node once anyway)
-    seen = set()
-    deduped = []
-    for a in collected:
-        nid = a.get("nodeId")
-        if nid in seen:
-            continue
-        seen.add(nid)
-        deduped.append(a)
-
-    out = {
-        "generatedAt": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+    cli = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    cli.add_argument("--file", help="key of the Figma file")
+    cli.add_argument("--nodes", help="frame node-ids, separated by commas")
+    cli.add_argument("--mapping", help="mapping JSON; its figmaFileKey and figmaNodes fill in for missing flags")
+    cli.add_argument("--from-mcp", help="JSON dump of annotations taken through MCP")
+    cli.add_argument("--local", help="screen folder of a design export that contains tree.json")
+    cli.add_argument("--source", default="auto", choices=["auto", "rest", "mcp", "local"])
+    cli.add_argument("--token", help="Figma token; FIGMA_ACCESS_TOKEN or the keychain is safer since other processes can read argv")
+    cli.add_argument("--ca-file", help="PEM roots to trust when a proxy intercepts TLS")
+    cli.add_argument("--out", help="file to write; stdout when omitted")
+    opts = cli.parse_args()
+
+    file_key = opts.file
+    nodes = [piece for piece in (opts.nodes or "").split(",") if piece.strip()]
+    if opts.mapping:
+        mapping = read_json(opts.mapping)
+        file_key = file_key or mapping.get("figmaFileKey")
+        nodes = nodes or list(mapping.get("figmaNodes") or [])
+
+    source, found, files, audited = pick_source(opts, cli, file_key, nodes)
+
+    first_seen = {}
+    for item in found:
+        first_seen.setdefault(item["nodeId"], item)
+    unique = list(first_seen.values())
+
+    def having(lang):
+        return sum(1 for entry in unique if entry[lang])
+
+    result = {
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
         "source": source,
         "files": files,
-        "auditedNodes": [canon_id(n) for n in node_ids],
-        "count": len(deduped),
-        "withTr": sum(1 for a in deduped if a.get("tr") is not None),
-        "withEn": sum(1 for a in deduped if a.get("en") is not None),
-        "annotations": deduped,
+        "auditedNodes": audited,
+        "count": len(unique),
+        "withTr": having("tr"),
+        "withEn": having("en"),
+        "annotations": unique,
     }
-
-    text = json.dumps(out, ensure_ascii=False, indent=2)
-    if args.out:
-        with open(args.out, "w", encoding="utf-8") as fh:
-            fh.write(text + "\n")
-        sys.stderr.write(f"# {out['count']} annotated node(s) "
-                         f"(tr={out['withTr']} en={out['withEn']}, source={source}) → {args.out}\n")
+    text = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    if not opts.out:
+        sys.stdout.write(text)
     else:
-        sys.stdout.write(text + "\n")
-
-    only_tr = [a["nodeId"] for a in deduped if a.get("tr") and not a.get("en")]
-    if only_tr:
-        sys.stderr.write(f"# {len(only_tr)} annotation(s) have TR but no EN "
-                         "(flag back to the content team): " + ", ".join(only_tr) + "\n")
+        with open(opts.out, "w", encoding="utf-8") as sink:
+            sink.write(text)
+        print(f"# {result['count']} annotations ({result['withTr']} TR, {result['withEn']} EN) from {source} -> {opts.out}", file=sys.stderr)
+
+    missing_en = [entry["nodeId"] for entry in unique if entry["tr"] and not entry["en"]]
+    if missing_en:
+        print(f"# {len(missing_en)} annotation(s) carry TR copy without EN; return them to the content team:", file=sys.stderr)
+        for node_id in missing_en:
+            print(f"#   {node_id}", file=sys.stderr)
 
 
 if __name__ == "__main__":