A class that performs translations between a pair of languages.
This class provides a flexible way for you to translate one or more lines of text at a time.
There are two ways in which you can initialize a `TranslationSession`.
One way you can obtain an instance of this class is by adding a `.translationTask()` to a SwiftUI view within your app.
You can either add a <doc://com.apple.documentation/documentation/swiftui/view/translationtask(_:action:)> or a <doc://com.apple.documentation/documentation/swiftui/view/translationtask(source:target:action:)>
function to the SwiftUI view containing the content you want to translate, like a <doc://com.apple.documentation/documentation/swiftui/text> view.
After adding the task, the function passes you an instance of a translation session in its `action` closure.
With this instance, you can use one or more of the translate functions to translate a single string or multiple strings of text.
Another way for contexts where there's no UI, you can directly initialize the TranslationSession using ``TranslationSession/init(installedSource:target:)`` to translate between languages.
This initializer requires that you specify which source language you use and throws an error if the languages aren't already installed on the person's device.
The following example demonstrates how to translate a single string of text within a SwiftUI view:
struct TranslationExample: View {
var sourceText: String
var sourceLanguage: Locale.Language?
var targetLanguage: Locale.Language?
@State private var targetText: String?
var body: some View {
Text(targetText ?? sourceText)
.translationTask(
source: sourceLanguage,
target: targetLanguage
) { session in
do {
let response = try await session.translate(sourceText)
targetText = response.targetText
} catch {
// Handle error.
}
}
}
}
- Note: All translations using the `TranslationSession` class are processed on the user’s device. Apple
may collect API usage and performance metrics including the app bundle ID and the original and translated
language, but this data does not include the original or translated content.
Members (13)
method · iOS 18.0+
prepareTranslation
TypeScript
prepareTranslation(): Promise<void>
Swift declaration
func prepareTranslation() async throws
Asks for permission to download translation languages without doing any translations.
If you know ahead of time which languages the person needs to translate,
you can prompt them to download those languages in advance by calling this method.
When you call this method, the framework asks the person for permission to download the
``sourceLanguage`` and ``targetLanguage``.
If the languages are already installed or in the middle of downloading, the function returns
without prompting them.
If you call this function when the `sourceLanguage` is `nil`, it throws
``TranslationError/unableToIdentifyLanguage`` error, since there's no sample text to
identify which source language to use for translation.
Translates multiple strings of text of the same language, returning the results all at once when complete.
This function translates multiple strings as a batch and might display different UI depending on the state of the translation.
The app doesn't need to install the required languages before calling this method.
Pass in the strings of text you want to translate as an array of the ``Request`` type.
To create requests for attributed strings, use ``Request/init(sourceText:clientIdentifier:)-(AttributedString)``.
This method takes longer to return than ``translate(batch:)``, but it has the advantage
of not mapping translation requests to responses.
The responses return in the same order the requests are sent.
If the required languages for translation have already downloaded and the source language is clear,
this function returns results without showing any further prompts to the person.
If the source or target language aren't installed, the framework asks the person for permission to
download the languages. During download a progress indicator displays. After the download completes,
the framework performs the translation.
If the `sourceLanguage` is `nil` and the framework can't detect the source language from the content,
the framework prompts the person to choose the source language.
The framework only supports string translations of the same language.
The strings must either match the `sourceLanguage` you set in the configuration,
or if the `sourceLanguage` is `nil`, be of the same language.
This function throws an `Error` if:
- The person doesn't agree to downloading the languages
- The person dismisses the progress view during language downloads
- ``TranslationSession`` fails system validation
- The session doesn't allow requesting downloads and languages aren't installed
- You already cancelled the session
- Something goes wrong during translation
If a person dismisses the progress view while the languages download, the system throws a <doc://com.apple.documentation/documentation/foundation/cocoaerror/code/usercancelled> error, and the languages
continue to download in the background.
- Note: Calls to this function can take several minutes while languages download.
- Parameters:
- batch: The array of requests to translate.
- Returns: An array of responses containing the text translations matching the order they were sent.
get · iOS 18.0+
sourceLanguage
TypeScript
get sourceLanguage(): (_Foundation_Locale_Language) | null
Swift declaration
final let sourceLanguage: Locale.Language?
The input language to translate from.
If this value is set to `nil`, the session tries to identify the source language automatically.
If it can't identify the language, it prompts the person to choose the source language to use for the translation.
- Note: This value doesn't update after translation. To see what source language
the session uses for a particular translation, check the response ``TranslationSession/Response/sourceLanguage``.
get · iOS 18.0+
targetLanguage
TypeScript
get targetLanguage(): (_Foundation_Locale_Language) | null
Swift declaration
final let targetLanguage: Locale.Language?
The output language to translate into.
If this value is set to `nil`, the session chooses an optimal language to translate into
based on the `sourceLanguage` and the person's <doc://com.apple.documentation/documentation/foundation/locale/preferredlanguages>.
- Note: This value doesn't update after translation. To see what target language
the session uses for a particular translation, check the response ``TranslationSession/Response/targetLanguage``.
Creates a translation session to translate between a given source and target language already
installed on device.
If one or both languages aren't installed on the device, attempting to translate will
throw errors. To get the person's permission to download languages that aren't already
installed, translate using a ``TranslationSession`` provided by <doc://com.apple.documentation/documentation/swiftui/view/translationtask(_:action:)> or
<doc://com.apple.documentation/documentation/swiftui/view/translationtask(source:target:action:)> .
- Note: If you created `TranslationSession` using
``TranslationSession/init(installedSource:target:)``, you don't need a
`.translationTask()`; however, you will need a ``sourceLanguage`` .
- Parameters:
- installedSource: The language the source content is in. All text translated with this session
should be in the same source language.
- targetLanguage: The language to translate content into. A `nil` value means the session
picks a target based on the person's `Locale.preferredLanguages`, and the
`sourceLanguage`.
- preferredStrategy: The translation approach to use.
``TranslationSession/Strategy/highFidelity`` uses Apple Intelligence
models when available on device, or falls back to ``TranslationSession/Strategy/lowLatency``
when those models aren't available. The `lowLatency` strategy uses traditional
models for translation.
Creates a translation session to translate between a given source and target language already installed on device.
If one or both of the languages aren't installed on the device already, attempting to translate will throw errors. In order to get the person's permission to download
languages that aren't already installed, translate using a `TranslationSession` provided by <doc://com.apple.documentation/documentation/swiftui/view/translationtask(_:action:)> or
<doc://com.apple.documentation/documentation/swiftui/view/translationtask(source:target:action:)> .
- Note: If you created `TranslationSession` using ``TranslationSession/init(installedSource:target:)``, you don't need a `.translationTask()`, however, you will need a `sourceLanguage` .
get · iOS 26.4+
preferredStrategy
TypeScript
get preferredStrategy(): TranslationSession_Strategy
Swift declaration
var preferredStrategy: TranslationSession.Strategy { get }
The preferred translation strategy configured for the session.
get · iOS 26.0+
canRequestDownloads
TypeScript
get canRequestDownloads(): boolean
Swift declaration
var canRequestDownloads: Bool { get }
A boolean value that indicates whether a translation session can request language downloads.
If this property is true, then the system prompts the person to authorize downloading additional languages if they aren't already installed.
If this property is false, then the session cannot request language downloads and will throw the error ``TranslationError/notInstalled`` if you attempt to translate and the languages aren't installed.
- Note: A session created using `.translationTask()` can always request downloads, however when it's created directly using ``TranslationSession/init(installedSource:target:)`` it cannot request downloads. The system only throws an error when attempting to translate and the languages aren't installed.
method · iOS 26.0+
cancel
TypeScript
cancel(): void
Swift declaration
func cancel()
Attempts to stop all ongoing work for the translation session.
Future requests will throw an error that the session is already cancelled.
get · iOS 26.0+
isReady
TypeScript
get isReady(): Promise<boolean>
Swift declaration
var isReady: Bool { get async }
A boolean value that indicates whether the system has installed the source and target languages of the session and is ready to begin translation.
Use this property to check whether a translation is likely to succeed. In a session that can request downloads, it prompts the person to approve downloads if languages aren't ready yet.
In a session that can't request downloads, it will throw an error if the person calls any functions when languages aren't ready.
If languages aren't installed, attach a <doc://com.apple.documentation/documentation/swiftui/view/translationtask(_:action:)> or a
<doc://com.apple.documentation/documentation/swiftui/view/translationtask(source:target:action:)> function to a SwiftUI View.
Then, call either ``TranslationSession/prepareTranslation()`` or one of the translate functions so the system prompts the person to approve the language downloads.
- Note: This value returns whether the languages are currently installed. The person or system can still delete the downloaded languages after calling this, so make sure you handle the appropriate errors when calling one of the translate functions.
Translates multiple strings of text of the same language, returning a sequence of responses as they're available.
This function translates multiple strings of text incrementally and might display different UI depending
on the state of the translation.
The app doesn't need to install the required languages before calling this method.
Pass in the strings of text you want to translate as an array of the ``Request`` type.
To create requests for attributed strings, use ``Request/init(sourceText:clientIdentifier:)-(AttributedString)``.
Set the ``Request/clientIdentifier`` on each request so you can match the request
with the response as the translations incrementally return.
If the required languages for translation have already downloaded and the source language is clear,
this function returns results without showing any UI to the person.
If the source or target language aren't installed, the framework asks the person for permission to
download the languages. During the download a progress indicator displays. After it completes,
the framework performs the translation.
If the `sourceLanguage` is `nil` and the framework can't detect the source language from the content,
the framework prompts the person to choose the source language.
The framework only supports string translations of the same language.
The strings must either match the `sourceLanguage` you set in the configuration,
or if the `sourceLanguage` is `nil`, be of the same language.
This function throws an `Error` if:
- The person doesn't agree to downloading the languages
- The person dismisses the progress view during language downloads
- ``TranslationSession`` fails system validation
- The session doesn't allow requesting downloads and languages aren't installed
- You already cancelled the session
- Something goes wrong during translation
If a person dismisses the progress view while the languages download, the system throws a <doc://com.apple.documentation/documentation/foundation/cocoaerror/code/usercancelled> error, and the languages
continue to download in the background.
- Note: Calls to this function can take several minutes while languages download. The framework
shows a progress indicator during the download.
- Parameters:
- batch: The array of requests to translate.
- Returns: An `AsyncSequence` of responses containing the text translations.
Translates a formatted string of text, preserving formatting in the translation.
Use this method to translate text that includes formatting like bold text or links,
and preserve that formatting in the translated result. The framework aligns formatting
between the source and target languages so that formatted words in the source remain
formatted in the translation. Custom attributes, such as timestamps for synchronized
captions or lyrics, are also preserved. For examples of translating attributed strings, see
``TranslationSession/Request/attributedSourceText``.
This function translates a single line of text and might display different UI depending on the state of
the translation. The app doesn't need to install the required languages before calling this method.
The function handles translation based on language availability:
- If the required languages are already downloaded and the source language is clear,
the function returns results without showing any UI to the person.
- If the source or target language aren't installed, the framework asks the person for permission to
download the languages. During the download a progress indicator displays. After it completes,
the framework performs the translation.
- If the ``sourceLanguage`` is `nil` and the framework can't detect it from the content,
the framework prompts the person to choose the source language.
This function throws an `Error` if:
- The person doesn't agree to downloading the languages
- The person dismisses the progress view during language downloads
- ``TranslationSession`` fails system validation
- The session doesn't allow requesting downloads and languages aren't installed
- You already cancelled the session
- Something goes wrong during translation
If a person dismisses the progress view while the languages download, the system throws a <doc://com.apple.documentation/documentation/foundation/cocoaerror/code/usercancelled> error, and the languages
continue to download in the background.
- Note: This function call can take several minutes while languages download.
- Parameters:
- string: The formatted text to translate.
- Returns: The response that contains the text translation with formatting preserved.
Translates a single string of text.
This function translates a single line of text and might display different UI depending on the state of the translation.
The app doesn't need to install the required languages before calling this method.
If the required languages for translation have already downloaded and the source language is clear,
this function returns results without showing any UI to the person.
If the source or target language aren't installed, the framework asks the person for permission to
download the languages. During the download a progress indicator displays. After it completes,
the framework performs the translation.
If the `sourceLanguage` is `nil` and the framework can't detect the source language from the content,
the framework prompts the person to choose the source language.
This function throws an `Error` if:
- The person doesn't agree to downloading the languages
- The person dismisses the progress view during language downloads
- ``TranslationSession`` fails system validation
- The session doesn't allow requesting downloads and languages aren't installed
- You already cancelled the session
- Something goes wrong during translation
If a person dismisses the progress view while the languages download, the system throws a <doc://com.apple.documentation/documentation/foundation/cocoaerror/code/usercancelled> error, and the languages
continue to download in the background.
- Note: This function call can take several minutes while languages download.
- Parameters:
- string: The string of plain text to translate.
- Returns: The response containing the text translation.
