System Overview

1. Event Source (Clipboard/Pasteboard)
   • Observe NSPasteboard.general for change count increments.
   • Debounce to avoid rapid duplicate triggers (e.g., 150–300 ms).
2. Language Identification
   • Lightweight heuristic (Unicode ranges, common stopwords) or ML model.
   • Skip translation when source ≈ target or confidence < threshold.
3. Translation Engine Abstraction
   • Adapter interface (e.g., translate(text, source, target) -> string).
   • Pluggable providers: OpenAI/Anthropic, DeepL, Google, LibreTranslate, local LLM (Ollama).
   • Backoff + retry; deterministic formatting (preserve punctuation/newlines).
4. Privacy & Security
   • Opt-in sending: only the copied text; never full clipboard history.
   • Local redaction rules (emails, tokens) before network calls.
   • API keys stored in Keychain; TLS enforced; no telemetry by default.
5. Delivery & UX
   • Menu bar app with quick toggle, target-language picker, history.
   • Output modes: notification banner, menubar popover, auto-paste (Cmd+V injection with user consent).
   • Inline polish: keep capitalization, handle code blocks, don’t translate URLs or code.
6. Performance
   • Async translation on a background queue.
   • Caching (LRU) by hash(text, src, tgt) to eliminate repeats.
   • Rate limiting to avoid provider throttling.
7. Accessibility & Internationalization
   • Full keyboard control (global hotkey to replay last translation).
   • VoiceOver labels; adjustable font sizes.
   • Bi-di text handling; preserve RTL/LTR directionality.
8. Failure Modes
   • Offline: fall back to local model or show “tap to retry.”
   • Provider error: rotate to next provider; surface error code.
   • Large text: chunk by sentence with rejoin rules; maintain paragraph structure.
9. Safety & Style Constraints
   • Never translate inside code spans/backticks.
   • Respect user dictionary/terminology (project glossary).
   • Optional “formal/casual” tone control for engines that support it.
10. Telemetry (Optional, Off by Default)
    • Count of successful translations and average latency, no text content.
    • Helps tune debouncing, chunk size, and provider selection.

Design Trade-offs

• Cloud vs Local LLM: Cloud gives accuracy/speed; local preserves privacy. Hybrid with user choice is ideal.
• Always-on vs Hotkey: Always-on maximizes convenience but risks noise; hotkey reduces surprises.
• Notifications vs Paste-back: Notifications are safe; paste-back is fastest but needs explicit opt-in.

Future Extensions

OCR for images in clipboard (Vision framework).

On-screen selection translation via accessibility APIs.

• GitHub
• LinkedIn