#!/usr/bin/env python3
"""
scripts/check_markup.py

Verify Sphinx markup consistency between msgid and msgstr:
  - Roles like :term:`text `  the *target* (or the whole role, if
    it has no explicit target) must match; the display text is expected to
    be translated, matching Sphinx's own translation convention.
  - Literal/code spans (``...``), substitution refs (|...|), and %s/{name}
    placeholders  these must match verbatim, since they're not prose.
  - Invalid C-string escape sequences in msgstr (a lone backslash followed
    by a character that isn't a valid escape, see VALID_ESCAPE_CHARS)  these
    make `msgfmt` fail with "invalid control sequence" and must be found
    before they break a build.
  - Files that cannot be parsed at all are reported (and fail the run)
    instead of aborting it, so one broken file doesn't hide findings in the
    rest.

Fuzzy entries are checked too: the docs are built with
gettext_allow_fuzzy_translations=1, so they reach the rendered output.

Output is grouped by file, with a per-file mismatch count and a grand
total at the end. Exits 1 if anything was found.

Requires: pip install polib

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 collections import Counter
from pathlib import Path

import polib

ROLE_PATTERN = re.compile(r":((?:\w+:)?[\w.-]+):`([^`]+)`")
# Sphinx itself accepts `label` (no space) as well as the more
# common `label ` -- both are valid RST role syntax, and the
# upstream English source uses the no-space form in a few places (e.g.
# ":pypi:`file built`"). The space before "