Translation

On-device, privacy-preserving text translation on Apple platforms. Two distinct front doors: a one-line system overlay (.translationPresentation) and a programmatic API (TranslationSession obtained through .translationTask). The deep API reference — every modifier, batch method, availability/download flow, and use-case recipe — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. MODE — overlay (default; .translationPresentation(isPresented:text:) shows Apple's system UI, zero state to manage, single string) · programmatic (TranslationSession via .translationTask when you render the result in your own UI, batch, or store it).
2. LANGUAGES — auto (default; source: nil auto-detects, target: nil uses the user's preferred language) · fixed (explicit Locale.Language pair; required for prepareTranslation() pre-downloads and for separating mixed-language batches).
3. ASSETS — on-demand (default; first translation prompts the system download if the pair is .supported but not .installed) · prepared (call prepareTranslation() behind a user action to download ahead of time for offline use).

When to use

Building or reviewing any in-app translation of user-facing or user-generated text — chat messages, product descriptions, documents, comments. Use overlay for a single user-initiated translation with system UI; use programmatic when the translated text lives in your own views or model. Not for app UI localization (that's String(localized:) / string catalogs) and not for server-side or cross-dialect conversion.

Core rules