TextTranslationClient Class

Text translation is a cloud-based REST API feature of the Translator service that uses neural machine translation technology to enable quick and accurate source-to-target text translation in real time across all supported languages.

The following methods are supported by the Text Translation feature:

Languages. Returns a list of languages supported by Translate, Transliterate, and Dictionary Lookup operations.

Translate. Renders single source-language text to multiple target-language texts with a single request.

Transliterate. Converts characters or letters of a source language to the corresponding characters or letters of a target language.

Detect. Returns the source code language code and a boolean variable denoting whether the detected language is supported for text translation and transliteration.

Dictionary lookup. Returns equivalent words for the source term in the target language.

Dictionary example Returns grammatical structure and context examples for the source term and target term pair.

Combinations of endpoint and credential values: str + AzureKeyCredential - used custom domain translator endpoint str + AzureKeyCredential + Region - used for global translator endpoint str + AsyncTokenCredential - used for regional endpoint with token authentication str + None - used with text translation on-prem container None + AzureKeyCredential - used for global translator endpoint with global Translator resource None + AsyncTokenCredential - general translator endpoint with token authentication None + AsyncTokenCredential + Region - general translator endpoint with regional Translator resource

Inheritance
azure.ai.translation.text.aio._client.TextTranslationClient
TextTranslationClient

Constructor

TextTranslationClient(*, credential: AsyncTokenCredential, region: str | None = None, endpoint: str | None = None, resource_id: str | None = None, audience: str | None = None, api_version: str = '3.0', **kwargs)

Keyword-Only Parameters

Name Description
endpoint
str

Supported Text Translation endpoints (protocol and hostname, for example: https://api.cognitive.microsofttranslator.com). If not provided, global translator endpoint will be used.

credential
Union[<xref:AzureKeyCredential>, <xref:AsyncTokenCredential>]

Credential used to authenticate with the Translator service

region
str

Used for National Clouds.

resource_id
str

Used with both a TokenCredential combined with a region.

audience
str

Scopes of the credentials.

api_version
str

Default value is "3.0". Note that overriding this default value may result in unsupported behavior.

Methods

close
find_sentence_boundaries
get_supported_languages

Gets the set of languages currently supported by other operations of the Translator.

Gets the set of languages currently supported by other operations of the Translator.

lookup_dictionary_entries
lookup_dictionary_examples

Lookup Dictionary Examples.

Lookup Dictionary Examples.

send_request

Runs the network request through the client's chained policies.


>>> from azure.core.rest import HttpRequest
>>> request = HttpRequest("GET", "https://www.example.org/")
<HttpRequest [GET], url: 'https://www.example.org/'>
>>> response = await client.send_request(request)
<AsyncHttpResponse: 200 OK>

For more information on this code flow, see https://aka.ms/azsdk/dpcodegen/python/send_request

translate
transliterate

close

async close() -> None

find_sentence_boundaries

async find_sentence_boundaries(body: List[str] | List[InputTextItem] | IO[bytes], *, client_trace_id: str | None = None, language: str | None = None, script: str | None = None, **kwargs: Any) -> List[BreakSentenceItem]

Parameters

Name Description
body
Required

Keyword-Only Parameters

Name Description
client_trace_id
Required
language
Required
script
Required

get_supported_languages

Gets the set of languages currently supported by other operations of the Translator.

Gets the set of languages currently supported by other operations of the Translator.

async get_supported_languages(*, client_trace_id: str | None = None, scope: str | None = None, accept_language: str | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> GetSupportedLanguagesResult

Keyword-Only Parameters

Name Description
client_trace_id
str

A client-generated GUID to uniquely identify the request. Default value is None.

scope
str

A comma-separated list of names defining the group of languages to return. Allowed group names are: translation, transliteration and dictionary. If no scope is given, then all groups are returned, which is equivalent to passing scope=translation,transliteration,dictionary. To decide which set of supported languages is appropriate for your scenario, see the description of the <xref:response-body>. Default value is None.

accept_language
str

The language to use for user interface strings. Some of the fields in the response are names of languages or names of regions. Use this parameter to define the language in which these names are returned. The language is specified by providing a well-formed BCP 47 language tag. For instance, use the value fr to request names in French or use the value zh-Hant to request names in Chinese Traditional. Names are provided in the English language when a target language is not specified or when localization is not available. Default value is None.

etag
str

check if resource is changed. Set None to skip checking etag. Default value is None.

match_condition

The match condition to use upon the etag. Default value is None.

Returns

Type Description

GetSupportedLanguagesResult. The GetSupportedLanguagesResult is compatible with MutableMapping

Exceptions

Type Description

Examples


   # response body for status code(s): 200
   response == {
       "dictionary": {
           "str": {
               "dir": "str",  # Directionality, which is rtl for
                 right-to-left languages or ltr for left-to-right languages. Required.
                 Known values are: "ltr" and "rtl".
               "name": "str",  # Display name of the language in the locale
                 requested via Accept-Language header. Required.
               "nativeName": "str",  # Display name of the language in the
                 locale native for this language. Required.
               "translations": [
                   {
                       "code": "str",  # Language code identifying
                         the target language. Required.
                       "dir": "str",  # Directionality, which is rtl
                         for right-to-left languages or ltr for left-to-right languages.
                         Required. Known values are: "ltr" and "rtl".
                       "name": "str",  # Display name of the
                         language in the locale requested via Accept-Language header.
                         Required.
                       "nativeName": "str"  # Display name of the
                         language in the locale native for this language. Required.
                   }
               ]
           }
       },
       "translation": {
           "str": {
               "dir": "str",  # Directionality, which is rtl for
                 right-to-left languages or ltr for left-to-right languages. Required.
                 Known values are: "ltr" and "rtl".
               "name": "str",  # Display name of the language in the locale
                 requested via Accept-Language header. Required.
               "nativeName": "str"  # Display name of the language in the
                 locale native for this language. Required.
           }
       },
       "transliteration": {
           "str": {
               "name": "str",  # Display name of the language in the locale
                 requested via Accept-Language header. Required.
               "nativeName": "str",  # Display name of the language in the
                 locale native for this language. Required.
               "scripts": [
                   {
                       "code": "str",  # Code identifying the
                         script. Required.
                       "dir": "str",  # Directionality, which is rtl
                         for right-to-left languages or ltr for left-to-right languages.
                         Required. Known values are: "ltr" and "rtl".
                       "name": "str",  # Display name of the script
                         in the locale requested via Accept-Language header. Required.
                       "nativeName": "str",  # Display name of the
                         language in the locale native for the language. Required.
                       "toScripts": [
                           {
                               "code": "str",  # Code
                                 identifying the script. Required.
                               "dir": "str",  #
                                 Directionality, which is rtl for right-to-left languages
                                 or ltr for left-to-right languages. Required. Known
                                 values are: "ltr" and "rtl".
                               "name": "str",  # Display
                                 name of the script in the locale requested via
                                 Accept-Language header. Required.
                               "nativeName": "str"  #
                                 Display name of the language in the locale native for the
                                 language. Required.
                           }
                       ]
                   }
               ]
           }
       }
   }

lookup_dictionary_entries

async lookup_dictionary_entries(body: List[str] | List[InputTextItem] | IO[bytes], *, from_language: str, to_language: str, client_trace_id: str | None = None, **kwargs: Any) -> List[DictionaryLookupItem]

Parameters

Name Description
body
Required

Keyword-Only Parameters

Name Description
from_language
Required
to_language
Required
client_trace_id
Required

lookup_dictionary_examples

Lookup Dictionary Examples.

Lookup Dictionary Examples.

async lookup_dictionary_examples(body: List[DictionaryExampleTextItem] | IO[bytes], *, from_language: str, to_language: str, client_trace_id: str | None = None, **kwargs: Any) -> List[DictionaryExampleItem]

Parameters

Name Description
body
Required

Defines the content of the request. Is either a [DictionaryExampleTextItem] type or a IO[bytes] type. Required.

Keyword-Only Parameters

Name Description
from_language
str

Specifies the language of the input text. The source language must be one of the supported languages included in the dictionary scope. Required.

to_language
str

Specifies the language of the output text. The target language must be one of the supported languages included in the dictionary scope. Required.

client_trace_id
str

A client-generated GUID to uniquely identify the request. Default value is None.

Returns

Type Description

list of DictionaryExampleItem

Exceptions

Type Description

Examples


   # response body for status code(s): 200
   response == [
       {
           "examples": [
               {
                   "sourcePrefix": "str",  # The string to concatenate
                     before the value of sourceTerm to form a complete example. Do not add
                     a space character, since it is already there when it should be. This
                     value may be an empty string. Required.
                   "sourceSuffix": "str",  # The string to concatenate
                     after the value of sourceTerm to form a complete example. Do not add
                     a space character, since it is already there when it should be. This
                     value may be an empty string. Required.
                   "sourceTerm": "str",  # A string equal to the actual
                     term looked up. The string is added with sourcePrefix and
                     sourceSuffix to form the complete example. Its value is separated so
                     it can be marked in a user interface, e.g., by bolding it. Required.
                   "targetPrefix": "str",  # A string similar to
                     sourcePrefix but for the target. Required.
                   "targetSuffix": "str",  # A string similar to
                     sourceSuffix but for the target. Required.
                   "targetTerm": "str"  # A string similar to sourceTerm
                     but for the target. Required.
               }
           ],
           "normalizedSource": "str",  # A string giving the normalized form of
             the source term. Generally, this should be identical to the value of the Text
             field at the matching list index in the body of the request. Required.
           "normalizedTarget": "str"  # A string giving the normalized form of
             the target term. Generally, this should be identical to the value of the
             Translation field at the matching list index in the body of the request.
             Required.
       }
   ]

send_request

Runs the network request through the client's chained policies.


>>> from azure.core.rest import HttpRequest
>>> request = HttpRequest("GET", "https://www.example.org/")
<HttpRequest [GET], url: 'https://www.example.org/'>
>>> response = await client.send_request(request)
<AsyncHttpResponse: 200 OK>

For more information on this code flow, see https://aka.ms/azsdk/dpcodegen/python/send_request

send_request(request: HttpRequest, *, stream: bool = False, **kwargs: Any) -> Awaitable[AsyncHttpResponse]

Parameters

Name Description
request
Required

The network request you want to make. Required.

Keyword-Only Parameters

Name Description
stream

Whether the response payload will be streamed. Defaults to False.

Returns

Type Description

The response of your network call. Does not do error handling on your response.

translate

async translate(body: List[str] | List[InputTextItem] | IO[bytes], *, to_language: List[str], client_trace_id: str | None = None, from_language: str | None = None, text_type: str | TextType | None = None, category: str | None = None, profanity_action: str | ProfanityAction | None = None, profanity_marker: str | ProfanityMarker | None = None, include_alignment: bool | None = None, include_sentence_length: bool | None = None, suggested_from: str | None = None, from_script: str | None = None, to_script: str | None = None, allow_fallback: bool | None = None, **kwargs: Any) -> List[TranslatedTextItem]

Parameters

Name Description
body
Required

Keyword-Only Parameters

Name Description
to_language
Required
client_trace_id
Required
from_language
Required
text_type
Required
category
Required
profanity_action
Required
profanity_marker
Required
include_alignment
Required
include_sentence_length
Required
suggested_from
Required
from_script
Required
to_script
Required
allow_fallback
Required

transliterate

async transliterate(body: List[str] | List[InputTextItem] | IO[bytes], *, language: str, from_script: str, to_script: str, client_trace_id: str | None = None, **kwargs: Any) -> List[TransliteratedText]

Parameters

Name Description
body
Required

Keyword-Only Parameters

Name Description
language
Required
from_script
Required
to_script
Required
client_trace_id
Required