feat(translate): on-device text translation via Apple Translation framework (macOS 15+)

[initcore0]

Replaces the approach of the closed PR #219 (dual-runtime Parakeet + Whisper translate). That design ran a second full ASR stack over audio the fast engine had already transcribed — duplicated inference, English-only, and drop-oldest/drain-timeout behavior that could silently lose dictated text. This PR keeps one ASR runtime and translates the text per session/utterance on-device, with a single hard rule: the fallback is always "leave the text untranslated", NEVER "lose text".

Design

Hidden-anchor TranslationSession (OpenWhisp/Services/AppleTranslationProvider.swift). Apple gives no direct initializer for TranslationSession; the only way to obtain one is SwiftUI's .translationTask(configuration:) modifier. The provider keeps a persistent invisible anchor — a 1×1, alpha-0, borderless, offscreen NSWindow hosting a SwiftUI view that carries the modifier — alive for the app's lifetime. Publishing a new TranslationSession.Configuration (re)triggers the modifier; the action holds the session and drains a MainActor request queue until the next configuration change. The configuration always uses a nil source language (the framework auto-detects the dictated language); only the target is pinned, and a request for a different target swaps the configuration so a fresh session serves it. prepareTranslation() runs once per session to surface the language-asset download flow; every request also carries a 12 s watchdog, so a missing asset or framework stall resolves to nil (caller keeps the original text) instead of hanging a dictation.

Dictation path (final text, no audio tap). When "Translate to English" is on, the language is non-English (or auto), and the active engine is ASR-only (Parakeet, Apple Speech, SpeechAnalyzer), completeFinalText translates the session's final transcript before the normal delivery/paste flow — identical for every streaming engine because it needs no audio tee. The arm decision is a pure core policy, TextTranslationPolicy.shouldTranslateFinal (mirroring how PR #219 structured DualRuntimeTranslationPolicy), capability-driven only — deliberately the exact complement of the engine-level translate predicate, so no session ever translates twice or falls in the gap (contract-tested across allEngineIDs). Details:

• Mid-refine finals skip translation (the tail is a spoken instruction and the content-prefix subtraction must keep matching byte-for-byte).
• liveChunks sessions fall back to a single final paste while armed, so the original language is never typed into the document first.
• effectiveTranslateToEnglish / outputLanguageForCleaning grow text-path-aware derivations, so refine prompts and the RefineOutputGuard expected script correctly anticipate English output.

Stream overlay. StreamOverlayServer already had an injected Translator closure seam honoring config.translationEnabled + config.targetLanguage — but nothing supplied it. StreamOverlayCoordinator.startServer() now injects the provider (any target language, not just English), and the overlay pane gets a small Translation section (toggle + target-language picker) so the seam is actually reachable. Overlay internals (reducer, server) are untouched beyond the constructor argument; PR #219's two-track captionTrack UI is left for a follow-up.

Offer gates. Menu bar and Dictation pane now read ONE predicate (AppState.translationOffered → TextTranslationPolicy.translationOffered): "Translate to English" is offered when the engine translates natively OR the text path exists (macOS 15+). A past bug was exactly these two surfaces disagreeing.

macOS availability

Everything framework-facing is gated #if canImport(Translation) + if #available(macOS 15.0, *). The app's deployment target stays macOS 14 (build.sh is unchanged): macOS 14 compiles and runs with the feature simply unavailable — ASR-only engines keep today's dimmed menu row / absent pane toggle, and sessions never arm the text path.

Tested vs. needs a manual pass

Unit-tested (swift test, 1914 green):

• TextTranslationPolicyTests — arm/offer/derivation rules, incl. the exactly-one-path-arms contract per engine and macOS-14 equivalence with the old LanguageResolver behavior.
• StreamOverlayServerTests.testFailedTranslationKeepsOriginalCaption — a nil-returning translator degrades to the original caption line (the never-lose-text rule at the seam now wired live).
• Existing overlay translator-seam and capability-matrix tests unchanged and green.

Needs your manual pass on macOS 15+ (the framework can't run under swift test):

• Live dictation with Parakeet / Apple Speech / SpeechAnalyzer + Translate to English on a non-English language — verify the pasted final is English and that a translator failure pastes the original transcript.
• The language-asset download prompt on first use (prepareTranslation fires from an invisible window — confirm the consent sheet actually appears; if it doesn't, the request times out safely and text passes through untranslated).
• Overlay translated subtitles end-to-end in OBS/browser (enable in Settings → Stream Overlay → Translation).
• Confirmation that the hidden 1×1 anchor window never becomes visible/clickable and that .translationTask fires from it on a menu-bar app.

Notes

• Written on top of main including the merged overlay-retirement PR fix(overlay): resumed speech replays old subtitles, settings edits kill capture, dictation pill on stream #221; the StreamOverlay area may still conflict slightly with any further open work there (StreamOverlayCoordinator/StreamOverlayPane touches are intentionally minimal).
• Do not merge — leaving open for manual testing.

🤖 Generated with Claude Code