Share via

TextTranslationClient Class

  • Reference

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 + TokenCredential - used for regional endpoint with token authentication str + TranslatorCredential - used for National Clouds None + AzureKeyCredential - used for global translator endpoint with global Translator resource None + Token - general translator endpoint with token authentication None + TranslatorCredential - general translator endpoint with regional Translator resource

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

Constructor

TextTranslationClient(credential: AzureKeyCredential | AsyncTokenCredential | TranslatorCredential, *, endpoint: str | None = None, api_version='3.0', **kwargs)

Parameters

Name Description
endpoint
Required
str

Supported Text Translation endpoints (protocol and hostname, for example: https://api.cognitive.microsofttranslator.com). Required.
credential
Required
Union[<xref:AzureKeyCredential> , <xref:AsyncTokenCredential> , TranslatorCredential]

Credential used to authenticate with the Translator service

Keyword-Only Parameters

Name Description
api_version
str

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

Default value: 3.0
endpoint
Required

Methods

close
find_sentence_boundaries

Find Sentence Boundaries.

Find Sentence Boundaries.
get_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 Entries.

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

Translate Text.

Translate Text.
transliterate

Transliterate Text.

Transliterate Text.

close 

async close() -> None

find_sentence_boundaries

Find Sentence Boundaries.

Find Sentence Boundaries.

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

Parameters

Name Description
content
Required
list[InputTextItem] or IO

Array of the text for which values the sentence boundaries will be calculated. Is either a [InputTextItem] type or a IO type. Required.

Keyword-Only Parameters

Name Description
client_trace_id
str

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

Language tag identifying the language of the input text. If a code isn't specified, automatic language detection will be applied. Default value is None.
script
str

Script tag identifying the script used by the input text. If a script isn't specified, the default script of the language will be assumed. Default value is None.
content_type
str

Body parameter Content-Type. Known values are: application/json. Default value is None.

Returns

Type Description
list[BreakSentenceItem]

list of BreakSentenceItem

Exceptions

Type Description
HttpResponseError

get_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_languages(*, client_trace_id: str | None = None, scope: str | None = None, accept_language: str | None = None, if_none_match: str | None = None, **kwargs: Any) -> GetLanguagesResult

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.
if_none_match
str

Passing the value of the ETag response header in an If-None-Match field will allow the service to optimize the response. If the resource has not been modified, the service will return status code 304 and an empty response body. Default value is None.

Returns

Type Description
GetLanguagesResult

GetLanguagesResult. The GetLanguagesResult is compatible with MutableMapping

Exceptions

Type Description
HttpResponseError

lookup_dictionary_entries

Lookup Dictionary Entries.

Lookup Dictionary Entries.

async lookup_dictionary_entries(content: List[InputTextItem] | IO, *, from_parameter: str, to: str, client_trace_id: str | None = None, **kwargs: Any) -> List[DictionaryLookupItem]

Parameters

Name Description
content
Required
list[InputTextItem] or IO

Array of the text to be sent to dictionary. Is either a [InputTextItem] type or a IO type. Required.

Keyword-Only Parameters

Name Description
from_parameter
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
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.
content_type
str

Body parameter Content-Type. Known values are: application/json. Default value is None.

Returns

Type Description
list[DictionaryLookupItem]

list of DictionaryLookupItem

Exceptions

Type Description
HttpResponseError

lookup_dictionary_examples

Lookup Dictionary Examples.

Lookup Dictionary Examples.

async lookup_dictionary_examples(content: List[DictionaryExampleTextItem] | IO, *, from_parameter: str, to: str, client_trace_id: str | None = None, **kwargs: Any) -> List[DictionaryExampleItem]

Parameters

Name Description
content
Required
list[DictionaryExampleTextItem] or IO

Array of the text to be sent to dictionary. Is either a [DictionaryExampleTextItem] type or a IO type. Required.

Keyword-Only Parameters

Name Description
from_parameter
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
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.
content_type
str

Body parameter Content-Type. Known values are: application/json. Default value is None.

Returns

Type Description
list[DictionaryExampleItem]

list of DictionaryExampleItem

Exceptions

Type Description
HttpResponseError

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, **kwargs: Any) -> Awaitable[AsyncHttpResponse]

Parameters

Name Description
request
Required
HttpRequest

The network request you want to make. Required.

Keyword-Only Parameters

Name Description
stream
bool

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

Returns

Type Description
AsyncHttpResponse

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

translate

Translate Text.

Translate Text.

async translate(content: List[InputTextItem] | IO, *, to: List[str], client_trace_id: str | None = None, from_parameter: 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
content
Required
list[InputTextItem] or IO

Array of the text to be translated. Is either a [InputTextItem] type or a IO type. Required.

Keyword-Only Parameters

Name Description
to
list[str]

Specifies the language of the output text. The target language must be one of the supported languages included in the translation scope. For example, use to=de to translate to German. It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. For example, use to=de&to=it to translate to German and Italian. Required.
client_trace_id
str

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

Specifies the language of the input text. Find which languages are available to translate from by looking up supported languages using the translation scope. If the from parameter isn't specified, automatic language detection is applied to determine the source language.

You must use the from parameter rather than autodetection when using the dynamic dictionary feature. Note: the dynamic dictionary feature is case-sensitive. Default value is None.
text_type
str or TextType

Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Possible values are: plain (default) or html. Known values are: "plain" and "html". Default value is None.
category
str

A string specifying the category (domain) of the translation. This parameter is used to get translations from a customized system built with Custom Translator. Add the Category ID from your Custom Translator project details to this parameter to use your deployed customized system. Default value is: general. Default value is None.
profanity_action
str or ProfanityAction

Specifies how profanities should be treated in translations. Possible values are: NoAction (default), Marked or Deleted. Known values are: "NoAction", "Marked", and "Deleted". Default value is None.
profanity_marker
str or ProfanityMarker

Specifies how profanities should be marked in translations. Possible values are: Asterisk (default) or Tag. Known values are: "Asterisk" and "Tag". Default value is None.
include_alignment
bool

Specifies whether to include alignment projection from source text to translated text. Possible values are: true or false (default). Default value is None.
include_sentence_length
bool

Specifies whether to include sentence boundaries for the input text and the translated text. Possible values are: true or false (default). Default value is None.
suggested_from
str

Specifies a fallback language if the language of the input text can't be identified. Language autodetection is applied when the from parameter is omitted. If detection fails, the suggestedFrom language will be assumed. Default value is None.
from_script
str

Specifies the script of the input text. Default value is None.
to_script
str

Specifies the script of the translated text. Default value is None.
allow_fallback
bool

Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Possible values are: true (default) or false.

allowFallback=false specifies that the translation should only use systems trained for the category specified by the request. If a translation for language X to language Y requires chaining through a pivot language E, then all the systems in the chain (X → E and E → Y) will need to be custom and have the same category. If no system is found with the specific category, the request will return a 400 status code. allowFallback=true specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. Default value is None.
content_type
str

Body parameter Content-Type. Known values are: application/json. Default value is None.

Returns

Type Description
list[TranslatedTextItem]

list of TranslatedTextItem

Exceptions

Type Description
HttpResponseError

transliterate

Transliterate Text.

Transliterate Text.

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

Parameters

Name Description
content
Required
list[InputTextItem] or IO

Array of the text to be transliterated. Is either a [InputTextItem] type or a IO type. Required.

Keyword-Only Parameters

Name Description
language
str

Specifies the language of the text to convert from one script to another. Possible languages are listed in the transliteration scope obtained by querying the service for its supported languages. Required.
from_script
str

Specifies the script used by the input text. Look up supported languages using the transliteration scope, to find input scripts available for the selected language. Required.
to_script
str

Specifies the output script. Look up supported languages using the transliteration scope, to find output scripts available for the selected combination of input language and input script. Required.
client_trace_id
str

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

Body parameter Content-Type. Known values are: application/json. Default value is None.

Returns

Type Description
list[TransliteratedText]

list of TransliteratedText

Exceptions

Type Description
HttpResponseError