feat(i18n): the server's closed English vocabularies named in the reader's language (E30 S2)

- lib/vocab + the `vocab` locale area: TMDB crew jobs and departments, auto-tags (D1 A: the data stays English, the catalog is named at its one source, useTags), built-in download profiles, YouTube topics; held key-for-key to the backend's own lists by backendIds.contract. - Countries by ISO code: TMDB parse stores {code, name}; rows stored before are coded from TMDB's own country list in one request (run_enrich); Intl names them, historic codes (YU, SU, XI…) from the catalog. - Player tracks named from the language tag, forced/SDH flags and codec tail, not Plex's server-language displayTitle; no invented "Audio N" on the server. - Download lifecycle notices (shared / expiring / expired / evicted) named from data; the share notice carries the title. - Scheduler: the job result rides along as data and is named per key (dashboard + run notice). - Invite status named; a render crash's notice no longer shows the engine's English message. - Fix: YouTube links …/wiki/Humour, the tagger looked for "Humor" — Comedy never came from a topic.
2026-09-29 21:21:19 +02:00
parent f6298d29af
commit f3a85916ec
50 changed files with 1475 additions and 94 deletions
@@ -12,6 +12,7 @@ the row. The enrich batch + scheduler entry live here too so the whole TMDB inte

 import time
 from datetime import datetime, timezone
+from typing import cast

 import httpx
 from sqlalchemy import func, select
@@ -125,6 +126,11 @@ class TmdbClient:
        """Resolve an external id (imdb_id / tvdb_id) to TMDB items via /find."""
        return self._get(f"/find/{external_id}", {"external_source": source})

+    def countries(self) -> list[dict] | None:
+        """TMDB's country list: `[{iso_3166_1, english_name, native_name}]` (a JSON array, which
+        `_get`'s dict annotation does not describe)."""
+        return cast("list[dict] | None", self._get("/configuration/countries"))
+
    def fetch_person(self, person_id: int) -> dict | None:
        """One person's bio + combined credits (E5 S6), in a single append_to_response request."""
        return self._get(f"/person/{person_id}", {"append_to_response": "combined_credits"})
@@ -255,8 +261,12 @@ def parse_tmdb(payload: dict, media_type: str) -> dict:
            c.get("name") for c in (payload.get("production_companies") or []) if c.get("name")
        ][:8]
        or None,
+        # The ISO code beside TMDB's English name (E30): the client names the country in the reader's
+        # language from the code; the name is the fallback for a code it cannot name.
        "production_countries": [
-            c.get("name") for c in (payload.get("production_countries") or []) if c.get("name")
+            {"code": c.get("iso_3166_1") or None, "name": c["name"]}
+            for c in (payload.get("production_countries") or [])
+            if c.get("name")
        ]
        or None,
        "recommendations": recs or None,
@@ -357,13 +367,49 @@ def enrich_batch(db: Session, tmdb: TmdbClient, limit: int) -> int:
    return processed


+def _country(c: dict | str) -> dict:
+    """One stored production country as served: `{code, name}`. A row enriched before E30 stored the
+    bare English name; until `backfill_country_codes` reaches it, it serves with no code (the client
+    shows the name)."""
+    return c if isinstance(c, dict) else {"code": None, "name": c}
+
+
+def backfill_country_codes(db: Session, tmdb: TmdbClient) -> int:
+    """Give the countries stored before E30 (bare English names) their ISO codes, from TMDB's own
+    country list — the names came from that list, so they match it exactly. One request, and only
+    while such a row is left: re-fetching each title instead would take the enrichment batch days.
+    A name the list does not hold keeps no code. Returns the number of rows rewritten."""
+    stale = [
+        row
+        for model in (PlexItem, PlexShow)
+        for row in db.execute(
+            select(model).where(func.jsonb_typeof(model.production_countries[0]) == "string")
+        ).scalars()
+    ]
+    if not stale:
+        return 0
+    codes = {
+        c["english_name"]: c["iso_3166_1"]
+        for c in tmdb.countries() or []
+        if c.get("english_name") and c.get("iso_3166_1")
+    }
+    for row in stale:
+        row.production_countries = [
+            {"code": codes.get(c), "name": c} if isinstance(c, str) else c
+            for c in row.production_countries or []
+        ]
+    db.commit()
+    return len(stale)
+
+
 def run_enrich(db: Session) -> dict:
    """Scheduler entry point. No-op (never an error) when the TMDB key isn't configured."""
    if not sysconfig.get_str(db, "tmdb_api_key"):
        return {"enriched": 0, "skipped": "tmdb_api_key not set"}
    with TmdbClient(db) as tmdb:
+        coded = backfill_country_codes(db, tmdb)
        n = enrich_batch(db, tmdb, settings.tmdb_enrich_batch)
-    return {"enriched": n}
+    return {"enriched": n, **({"countries_coded": coded} if coded else {})}


 def resolve_library_guids(
@@ -445,7 +491,7 @@ def serve_block(db: Session, row, *, lang: str) -> dict | None:
        "keywords": row.keywords or [],
        "crew": row.crew or [],
        "studios": row.studios or [],
-        "production_countries": row.production_countries or [],
+        "production_countries": [_country(c) for c in row.production_countries or []],
        "recommendations": resolve_recs(db, row.recommendations, lang=lang),
        "backdrops": row.backdrops or [],
    }
@@ -917,7 +917,14 @@ def share_download(
            user_id=recipient.id,
            type="download_shared",
            title=(job.display_name or "A download") + " was shared with you",
-            data={"kind": "download_shared", "from": user.email, "job_id": job_id},
+            # The client names the notice in the reader's language from `data` (E30); the title is the
+            # English fallback only.
+            data={
+                "kind": "download_shared",
+                "from": user.email,
+                "job_id": job_id,
+                "title": job.display_name,
+            },
            commit=False,
        )
        db.commit()
@@ -1,5 +1,6 @@
 """Plex show/item detail: the show drill-down + the per-item player payload (markers, cast, nav)."""

+import re
 import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
@@ -342,6 +343,26 @@ def _episode_nav(db: Session, it: PlexItem) -> tuple[str | None, str | None]:
    return (keys[i - 1] if i > 0 else None), (keys[i + 1] if i < len(keys) - 1 else None)


+# The technical tail of Plex's track title — "English (AC3 5.1)" → "AC3 5.1".
+_TRACK_TAIL = re.compile(r"\(([^()]+)\)\s*$")
+
+
+def _track_naming(s: dict) -> dict:
+    """What the player names a track from (E30). Plex's `displayTitle` is in the SERVER's language
+    ("English (AC3 5.1)", "magyar Forced", "中文 (EAC3 Stereo)"), so it is sent only as the fallback
+    `label`; the client builds the name in the reader's language from the language tag, the
+    forced / SDH flags and the codec tail. No title and no language → no label (the client numbers it)."""
+    title = s.get("displayTitle") or s.get("language") or None
+    tail = _TRACK_TAIL.search(title) if title else None
+    return {
+        "label": title,
+        "lang_tag": s.get("languageTag") or None,
+        "forced": bool(s.get("forced")),
+        "hearing_impaired": bool(s.get("hearingImpaired")),
+        "detail": tail.group(1).strip() if tail else None,
+    }
+
+
@router.get("/item/{rating_key}")
 def item_detail(
    rating_key: str,
@@ -387,9 +408,7 @@ def item_detail(
                audio_streams.append(
                    {
                        "ord": len(audio_streams),
-                        "label": s.get("displayTitle")
-                        or s.get("language")
-                        or f"Audio {len(audio_streams) + 1}",
+                        **_track_naming(s),
                        "language": s.get("languageTag") or s.get("language"),
                        "default": bool(s.get("selected") or s.get("default")),
                    }
@@ -399,9 +418,7 @@ def item_detail(
                subtitle_streams.append(
                    {
                        "ord": len(subtitle_streams),
-                        "label": s.get("displayTitle")
-                        or s.get("language")
-                        or f"Subtitle {len(subtitle_streams) + 1}",
+                        **_track_naming(s),
                        "language": s.get("languageTag") or s.get("language"),
                        "codec": codec,
                        # Text subs (srt/ass/…) can be served as WebVTT tracks; image subs (PGS/VobSub)
@@ -115,7 +115,9 @@ def _record(name: str, **fields) -> None:
        _activity.setdefault(name, {}).update(fields)


-def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | None) -> None:
+def _notify_done(
+    db, actor_id: int, job_id: str, status: str, summary: str | None, result: dict | None = None
+) -> None:
    """Post a completion notice to the triggering admin's inbox (manual runs only). Best
    effort — a notification failure must never mask the job's own outcome."""
    try:
@@ -125,7 +127,7 @@ def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | Non
            type="scheduler",
            title=f"{job_id}: {status}",  # English fallback; UI renders translated from data
            body=summary,
-            data={"job_id": job_id, "status": status, "summary": summary},
+            data={"job_id": job_id, "status": status, "summary": summary, "result": result},
        )
    except Exception:
        db.rollback()
@@ -192,25 +194,41 @@ def _job(name: str, fn) -> None:
                status="skipped",
                last_finished=_now_iso(),
                last_result="paused",
+                result=_PAUSED,
                progress=None,
            )
            if actor_id is not None:
-                _notify_done(db, actor_id, name, "skipped", "sync paused")
+                _notify_done(db, actor_id, name, "skipped", "sync paused", _PAUSED)
                _audit_run(db, actor_id, name, "skipped", "sync paused", None)
            return
        with progress.bind(sink):
            result = fn(db)
        summary = _summarize(result)
+        data = _result_data(result)
        log.info("job %s -> %s", name, result)
-        _record(name, status="ok", last_finished=_now_iso(), last_result=summary, progress=None)
+        _record(
+            name,
+            status="ok",
+            last_finished=_now_iso(),
+            last_result=summary,
+            result=data,
+            progress=None,
+        )
        if actor_id is not None:
-            _notify_done(db, actor_id, name, "ok", summary)
+            _notify_done(db, actor_id, name, "ok", summary, data)
        _audit_run(db, actor_id, name, "ok", summary, result)
    except Exception as exc:
        db.rollback()
        log.exception("job %s failed", name, extra=logs.event("scheduler.job.failed", job=name))
        err = str(exc) or exc.__class__.__name__
-        _record(name, status="error", last_finished=_now_iso(), last_error=err, progress=None)
+        _record(
+            name,
+            status="error",
+            last_finished=_now_iso(),
+            last_error=err,
+            result=None,
+            progress=None,
+        )
        if actor_id is not None:
            _notify_done(db, actor_id, name, "error", err)
        _audit_run(db, actor_id, name, "error", err, None)
@@ -221,6 +239,21 @@ def _job(name: str, fn) -> None:
        db.close()


+# A skipped run's result, in the same shape as a job's own `{"skipped": …}`.
+_PAUSED = {"skipped": "sync paused"}
+
+
+def _result_data(result) -> dict | None:
+    """A job's result as the client names it in the reader's language (E30): the dict itself (counts,
+    a `skipped` / `reason` word, a nested dict per phase), `enrich`'s bare count as one. The one-line
+    `_summarize` is the English fallback — and what the audit log keeps."""
+    if isinstance(result, dict):
+        return result or None
+    if isinstance(result, int) and not isinstance(result, bool):
+        return {"enriched": result}
+    return None
+
+
 def _summarize(result) -> str | None:
    """Compact one-line rendering of a job's return value for the dashboard."""
    if result is None:
@@ -259,6 +292,7 @@ def scheduler_snapshot() -> dict:
                "last_started": a.get("last_started"),
                "last_finished": a.get("last_finished"),
                "last_result": a.get("last_result"),
+                "result": a.get("result"),
                "last_error": a.get("last_error"),
                "progress": a.get("progress"),
            }
@@ -115,7 +115,9 @@ _TOPIC_SLUGS = {
    "Tourism": "Travel",
    "Fashion": "Fashion & Beauty",
    "Physical_attractiveness": "Fashion & Beauty",
-    "Humor": "Comedy",
+    # YouTube links the British page (…/wiki/Humour); the key was "Humor", so no channel ever got Comedy
+    # from its topic (E30).
+    "Humour": "Comedy",
    "Entertainment": "Entertainment",
    "Film": "Film",
    "Television_program": "TV",