fix(i18n): every refusal the API answers is structured and said in the reader's language

~150 HTTPExceptions carried a hand-written English sentence as their detail,
shown verbatim under the Hungarian UI — in the blocking error dialog and on
every inline surface that printed HttpError.detail (sign-in, setup wizard,
change password, the passphrase gate, live search). Four also quoted an
upstream exception's text back to the user.

- app/refusal.py: `refused(status, reason, **params)` → {code: "refused",
  reason, …params}; localizeDetail translates errors.refused.<reason> with the
  params interpolated. "Unknown X" 404s use the existing not_found(what).
- sysconfig.set_value raises InvalidSetting (reason + bounds) instead of an
  English ValueError; the three writers answer it through setting_refused.
- The Plex connection/write/image failures log what the upstream said and
  answer a reason; the search scraper's failure is logged and answered as
  youtube/unavailable (it crashed refusal_reason before).
- HttpError.detail now only ever holds a translated reason: a string detail
  (only the framework's own can remain) is left out, so reading .detail is
  safe everywhere — including destructured, the hole the raw-detail source
  scan could not see. That scan and its five-file exception list are gone.
- Enforced: test_http_details.py fails on any HTTPException with a sentence
  for a detail; the contract test requires every refused reason and every
  not_found "what" in both languages, and no key for one that is gone.
- local/jsx-comment-text: a // inside JSX children renders as text; the rule
  is ten lines in eslint.config.js rather than eslint-plugin-react's ~1800
  lockfile lines.

backend/app/routes/plex/_shared.py

@@ -1,11 +1,11 @@
 """Shared helpers, serializers and constants for the plex route package."""
 
-from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
 from app import logs
 from app.models import PlexItem
 from app.plex.lookups import by_rating_key
+from app.routes._common import not_found
 
 log = logs.get_logger(__name__)
 
@@ -13,7 +13,7 @@ log = logs.get_logger(__name__)
 def item_or_404(db: Session, rating_key: str) -> PlexItem:
     it = by_rating_key(db, PlexItem, rating_key)
     if it is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex item")
+        raise not_found("plex_item")
     return it
 
 

backend/app/routes/plex/admin.py

@@ -2,12 +2,12 @@
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import (
@@ -20,6 +20,9 @@ from app.plex import sync as plex_sync
 from app.plex import watch_sync as plex_watch
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.utils import iso
+from app.refusal import refused
+
+log = logs.get_logger(__name__)
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -35,10 +38,15 @@ def test_connection(_: User = Depends(admin_user), db: Session = Depends(get_db)
             info = plex.server_info()
             sections = plex.sections()
             media_check = _media_check(db, plex, sections)
-    except PlexNotConfigured as e:
-        raise HTTPException(status_code=400, detail=str(e))
+    except PlexNotConfigured:
+        raise refused(400, "plex_not_configured") from None
     except PlexError as e:
-        raise HTTPException(status_code=422, detail=f"Plex connection failed: {e}")
+        # What the upstream said is for the log, not the toast: it can quote the server URL back.
+        log.warning(
+            "the Plex connection test failed",
+            extra=logs.event("plex.admin.connection_failed", reason=type(e).__name__, error=str(e)),
+        )
+        raise refused(422, "plex_unreachable") from None
     return {
         "ok": True,
         "server_name": info.get("friendlyName") or info.get("title1") or "Plex",
@@ -129,7 +137,7 @@ def watch_link_set(
     admin token, so no separate Plex login. Enabling it for the first time runs the one-time
     "Plex is master" import immediately so the owner's existing Plex history shows up in Siftlode."""
     if not sysconfig.get_bool(db, "plex_enabled"):
-        raise HTTPException(status_code=409, detail="The Plex module is disabled.")
+        raise refused(409, "plex_disabled")
     enabled = body.enabled
     link = db.execute(select(PlexLink).where(PlexLink.user_id == user.id)).scalars().first()
     if link is None:
@@ -150,6 +158,6 @@ def watch_import_now(user: User = Depends(admin_user), db: Session = Depends(get
     intersection; Siftlode-only states are preserved. Idempotent."""
     link = db.execute(select(PlexLink).where(PlexLink.user_id == user.id)).scalars().first()
     if link is None or not link.sync_enabled:
-        raise HTTPException(status_code=409, detail="Enable Plex watch-sync first.")
+        raise refused(409, "watch_sync_off")
     result = plex_watch.import_owner_watch_state(db, link)
     return {**_link_dict(link), "import": result}

backend/app/routes/plex/collections.py

@@ -9,6 +9,7 @@ from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import (
@@ -26,6 +27,10 @@ from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
 from app.plex.query import content_libs, runtime_by_key, top_art_keys
 from app.utils import like_escape
+from app.refusal import refused
+from app.routes._common import not_found
+
+log = logs.get_logger(__name__)
 
 # The most-restrictive → least ordering used to pick a collection's effective content rating from its
 # members (Plex shows one cert on the collection; we don't store it, so derive it).
@@ -234,7 +239,7 @@ def collection_detail(
     endpoints below."""
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     movies = (
         db.execute(
             select(PlexItem)
@@ -325,9 +330,9 @@ def collection_detail(
 def _editable_collection_or_403(db: Session, rating_key: str) -> PlexCollection:
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     if not _collection_editable(col):
-        raise HTTPException(status_code=403, detail="This collection is read-only")
+        raise refused(403, "collection_read_only")
     return col
 
 
@@ -362,14 +367,13 @@ def _write_or_pending_error(wrote: bool, e: Exception) -> HTTPException:
     Both use 422, NOT a 5xx: the frontend treats 502/503/504 as "gateway unreachable" and raises a
     sticky offline banner (see api/core.ts RETRIABLE_GATEWAY). A 422 surfaces the detail as an ordinary
     action-error toast, which is what both of these are — the app answered, it didn't go unreachable."""
-    if wrote:
-        detail = (
-            "Collection updated in Plex, but refreshing the local copy failed; "
-            f"it will reconcile on the next sync ({e})"
-        )
-    else:
-        detail = f"Plex write failed: {e}"
-    return HTTPException(status_code=422, detail=detail)
+    log.warning(
+        "a Plex collection write did not settle",
+        extra=logs.event(
+            "plex.collections.write_failed", wrote=wrote, reason=type(e).__name__, error=str(e)
+        ),
+    )
+    return refused(422, "collection_pending_sync") if wrote else refused(422, "plex_write_failed")
 
 
 class CreateCollectionIn(BaseModel):
@@ -389,7 +393,7 @@ def create_collection(
     title = body.title.strip()
     seed = body.item_rating_key
     if not title or not seed:
-        raise HTTPException(status_code=400, detail="title and item_rating_key are required")
+        raise refused(400, "collection_fields_required")
     if library:
         lib = (
             db.execute(select(PlexLibrary).where(PlexLibrary.plex_key == library)).scalars().first()
@@ -399,7 +403,7 @@ def create_collection(
         seed_item = by_rating_key(db, PlexItem, seed) or by_rating_key(db, PlexShow, seed)
         lib = db.get(PlexLibrary, seed_item.library_id) if seed_item else None
     if lib is None:
-        raise HTTPException(status_code=404, detail="Unknown library")
+        raise not_found("library")
     _reject_duplicate_name(db, lib.id, title)
     wrote = False
     try:
@@ -473,7 +477,7 @@ def collection_rename(
     col = _editable_collection_or_403(db, rating_key)
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     _reject_duplicate_name(db, col.library_id, title, exclude_rk=rating_key)
     lib = db.get(PlexLibrary, col.library_id)
     wrote = False
@@ -502,7 +506,7 @@ def collection_delete(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+        raise _write_or_pending_error(False, e) from None
     return {"deleted": rating_key}
 
 
@@ -521,13 +525,10 @@ def collection_set_editable(
     (IMDb/TMDb/…) can never be made editable — they're regenerated outside Plex."""
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     want = body.editable
     if want and (col.smart or _collection_source(col) != "collection"):
-        raise HTTPException(
-            status_code=400,
-            detail="Smart / auto-list collections can't be made editable",
-        )
+        raise refused(400, "collection_smart")
     col.editable = want
     db.commit()
     return _collection_card(col)

backend/app/routes/plex/detail.py

@@ -5,7 +5,7 @@ import time
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
@@ -30,6 +30,7 @@ from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
 from app.routes.plex._shared import _norm_lang, item_or_404
 from app.routes.plex.collections import _collection_source
+from app.routes._common import not_found
 
 log = logs.get_logger(__name__)
 
@@ -109,7 +110,7 @@ def show_detail(
     hu = _norm_lang(lang) == "hu"
     sh = by_rating_key(db, PlexShow, rating_key)
     if sh is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex show")
+        raise not_found("show")
     seasons = (
         db.execute(
             select(PlexSeason)

backend/app/routes/plex/playback.py

@@ -39,6 +39,8 @@ from app.plex import stream as plex_stream
 from app.plex import watch_sync as plex_watch
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.routes.plex._shared import item_or_404
+from app.refusal import refused
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -49,7 +51,7 @@ def _require_session(request: Request) -> int:
     low-sensitivity; a valid session is enough."""
     uid, _ = resolved_user_id(request)
     if not uid:
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     return uid
 
 
@@ -78,15 +80,17 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
         with SessionLocal() as db:
             key = imgcache.key_for(db, str(rating_key), v)
             if not key:
-                raise HTTPException(status_code=404, detail="No image")
+                raise not_found("image")
             plex = PlexClient(db)  # reads base URL + token now; the fetch below needs no DB
-    except PlexNotConfigured as e:
-        raise HTTPException(status_code=400, detail=str(e))
+    except PlexNotConfigured:
+        raise refused(400, "plex_not_configured") from None
     try:
         with plex:
             data, ct = plex.image_bytes(key, w, h)
-    except PlexError as e:
-        raise HTTPException(status_code=502, detail=f"Plex image fetch failed: {e}")
+    # silent-ok: a byte proxy for an <img>; the browser shows the placeholder and no reader sees the
+    # detail — the 502 is the whole answer, as for the person-image proxy below.
+    except PlexError:
+        raise refused(502, "image_fetch_failed") from None
     imgcache.write(cache_key, data, ct)
     return imgcache.response(data, ct)
 
@@ -214,7 +218,7 @@ def person_image(u: str, request: Request) -> Response:
     Signed-session auth (no DB) so it, like /image, never holds a pool connection during the fetch."""
     _require_session(request)
     if not u.startswith(plex_people.PERSON_IMG_HOST):
-        raise HTTPException(status_code=400, detail="Unsupported image host")
+        raise refused(400, "image_host")
     cache_key = "person_" + hashlib.sha1(u.encode()).hexdigest()
     hit = imgcache.read(cache_key)
     if hit:
@@ -224,7 +228,7 @@ def person_image(u: str, request: Request) -> Response:
             r = c.get(u)
             r.raise_for_status()
     except httpx.HTTPError:
-        raise HTTPException(status_code=502, detail="Image fetch failed")
+        raise refused(502, "image_fetch_failed")
     ct = r.headers.get("content-type", "image/jpeg")
     imgcache.write(cache_key, r.content, ct)
     return imgcache.response(r.content, ct)
@@ -444,7 +448,7 @@ def item_state(
     it = item_or_404(db, rating_key)
     status = body.status
     if status not in ("new", "watched", "hidden"):
-        raise HTTPException(status_code=400, detail="Invalid status")
+        raise refused(400, "invalid_status")
     st = (
         db.execute(
             select(PlexState).where(PlexState.user_id == user.id, PlexState.item_id == it.id)
@@ -546,7 +550,7 @@ def show_state(
     """Mark a whole show watched/unwatched (all its episodes) for the current user + push to Plex."""
     sh = by_rating_key(db, PlexShow, rating_key)
     if sh is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex show")
+        raise not_found("show")
     watched = body.watched
     eps = (
         db.execute(select(PlexItem).where(PlexItem.show_id == sh.id, PlexItem.kind == "episode"))
@@ -568,7 +572,7 @@ def season_state(
     """Mark a whole season watched/unwatched (all its episodes) for the current user + push to Plex."""
     se = by_rating_key(db, PlexSeason, rating_key)
     if se is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex season")
+        raise not_found("season")
     watched = body.watched
     eps = (
         db.execute(select(PlexItem).where(PlexItem.season_id == se.id, PlexItem.kind == "episode"))
@@ -606,10 +610,10 @@ def stream_session(
             "start_s": 0.0,
         }
     if plex_paths.local_media_path(db, it.file_path) is None:
-        raise HTTPException(status_code=404, detail="Media file not found on disk")
+        raise refused(404, "media_missing")
     s = plex_stream.start_session(db, it, user.id, start, audio, aoff, multi, transcode=transcode)
     if s is None:
-        raise HTTPException(status_code=404, detail="Media file not found on disk")
+        raise refused(404, "media_missing")
     # Report the REAL media start (the keyframe ffmpeg landed on, which hls.js zero-bases to), not the
     # requested offset — the client's absolute clock and the subtitle cue-shift both key off this.
     # `transcode`/`hw`/`tonemap` let the player show an honest cold-start ("Preparing stream…") and
@@ -640,7 +644,7 @@ def stream_file(
     it = item_or_404(db, rating_key)
     src = plex_paths.local_media_path(db, it.file_path)
     if src is None:
-        raise HTTPException(status_code=404, detail="Media file not found on disk")
+        raise refused(404, "media_missing")
     if download:
         # A clean, safe download name from the title + the real file extension.
         ext = src.suffix or (f".{it.container}" if it.container else "")
@@ -694,10 +698,10 @@ def stream_hls_file(
         or "\\" in filename
         or ".." in filename
     ):
-        raise HTTPException(status_code=404, detail="Not found")
+        raise not_found("file")
     s = plex_stream.current_session(user.id, str(rating_key))
     if s is None or s.id != session_id:
-        raise HTTPException(status_code=404, detail="No active playback session")
+        raise refused(404, "session_gone")
     path = s.dir / filename
     # Only a name THIS session can actually produce is worth waiting for: its own playlists, and a
     # segment of one of its own renditions whose predecessor is already on disk (ffmpeg writes them
@@ -707,14 +711,14 @@ def stream_hls_file(
     # past the produced region — or a deliberate flood of hopeless names — from parking threadpool
     # workers and their DB connections (see `artifact_may_arrive`).
     if not plex_stream.artifact_may_arrive(s, filename):
-        raise HTTPException(status_code=404, detail="Not available yet")
+        raise refused(404, "not_ready")
     timeout = 30 if ext == ".m3u8" else 20
     # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
     # whole timeout: this is a SYNC route on the ~40-slot threadpool, holding a pooled DB connection
     # with it, so every such wait is a worker (and a connection) parked for 20 s — an ordinary seek
     # past the produced region was enough to do it (round 5).
     if not plex_stream.wait_for(path, timeout, proc=s.proc):
-        raise HTTPException(status_code=404, detail="Not available yet")
+        raise refused(404, "not_ready")
     try:
         content = path.read_bytes()
     except OSError:
@@ -725,7 +729,7 @@ def stream_hls_file(
         # restarting at the playhead. Ordinary trigger: `loadSession` awaits the new session — which
         # kills and rmtrees the old one — before destroying the old hls instance, so the outgoing
         # instance's in-flight segment request races the rmtree on every seek-restart.
-        raise HTTPException(status_code=404, detail="No active playback session") from None
+        raise refused(404, "session_gone") from None
     return Response(
         content=content,
         media_type=_HLS_CT[ext],

backend/app/routes/plex/playlists.py

@@ -2,7 +2,7 @@
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import delete, func, select, update
 from sqlalchemy.orm import Session
@@ -19,7 +19,8 @@ from app.models import (
 )
 from app.plex.cards import leaf_card
 from app.plex.lookups import by_rating_key
-from app.routes._common import owned_or_404
+from app.routes._common import owned_or_404, not_found
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -116,7 +117,7 @@ def create_playlist(
 ) -> dict:
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     pl = PlexPlaylist(user_id=user.id, title=title)
     db.add(pl)
     db.flush()
@@ -182,7 +183,7 @@ def rename_playlist(
     pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     pl.title = title
     db.commit()
     count = (
@@ -219,7 +220,7 @@ def playlist_add_item(
     pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     it = by_rating_key(db, PlexItem, body.item_rating_key)
     if it is None:
-        raise HTTPException(status_code=404, detail="Unknown item")
+        raise not_found("item")
     exists = (
         db.execute(
             select(PlexPlaylistItem).where(