<!--
{
  "availability" : [
    "iOS: 26.4.0 -",
    "iPadOS: 26.4.0 -",
    "macCatalyst: 26.4.0 -",
    "macOS: 26.4.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Translation",
  "identifier" : "/documentation/Translation/TranslationSession/translate(_:)-59zi2",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "Translation"
    ],
    "preciseIdentifier" : "s:11Translation0A7SessionC9translateyAC8ResponseV10Foundation16AttributedStringVYaKF"
  },
  "title" : "translate(_:)"
}
-->

# translate(_:)

Translates a formatted string of text, preserving formatting in the translation.

```
func translate(_ string: AttributedString) async throws -> TranslationSession.Response
```

## Parameters

`string`

The formatted text to translate.

## Return Value

The response that contains the text translation with formatting preserved.

## Discussion

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
[`attributedSourceText`](/documentation/Translation/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`](/documentation/Translation/TranslationSession/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`](/documentation/Translation/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.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)