azure.ai.translation.text.aio package¶
- class azure.ai.translation.text.aio.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)[source]¶
- class azure.ai.translation.text.aio.TextTranslationClient(*, credential: AzureKeyCredential, region: str | None = None, endpoint: str | None = None, api_version: str = '3.0', **kwargs)
- class azure.ai.translation.text.aio.TextTranslationClient(*, endpoint: str, api_version: str = '3.0', **kwargs)
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
- Keyword Arguments:
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[AzureKeyCredential, 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.
- 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]¶
Find Sentence Boundaries.
Find Sentence Boundaries.
- Parameters:
body (list[InputTextItem] or IO[bytes]) – Defines the content of the request. Is either a [InputTextItem] type or a IO[bytes] type. Required.
- Keyword Arguments:
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.
- Returns:
list of BreakSentenceItem
- Return type:
- Raises:
Example
# response body for status code(s): 200 response == [ { "sentLen": [ 0 # An integer array representing the lengths of the sentences in the input text. The length of the array is the number of sentences, and the values are the length of each sentence. Required. ], "detectedLanguage": { "language": "str", # A string representing the code of the detected language. Required. "score": 0.0 # A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence. Required. } } ]
- 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¶
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.
- Keyword Arguments:
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,transliterationanddictionary. If no scope is given, then all groups are returned, which is equivalent to passingscope=translation,transliteration,dictionary. To decide which set of supported languages is appropriate for your scenario, see the description of the response object. 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
frto request names in French or use the valuezh-Hantto 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 (MatchConditions) – The match condition to use upon the etag. Default value is None.
- Returns:
GetSupportedLanguagesResult. The GetSupportedLanguagesResult is compatible with MutableMapping
- Return type:
- Raises:
Example
# 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. } ] } ] } } }
- 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]¶
Lookup Dictionary Entries.
Lookup Dictionary Entries.
- Parameters:
body (list[InputTextItem] or IO[bytes]) – Defines the content of the request. Is either a [InputTextItem] type or a IO[bytes] type. Required.
- Keyword Arguments:
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:
list of DictionaryLookupItem
- Return type:
- Raises:
Example
# response body for status code(s): 200 response == [ { "displaySource": "str", # A string giving the source term in a form best suited for end-user display. For example, if the input is "JOHN", the display form will reflect the usual spelling of the name: "John". Required. "normalizedSource": "str", # A string giving the normalized form of the source term. For example, if the request is "JOHN", the normalized form will be "john". The content of this field becomes the input to lookup examples. Required. "translations": [ { "backTranslations": [ { "displayText": "str", # A string giving the source term that is a back-translation of the target in a form best suited for end-user display. Required. "frequencyCount": 0, # An integer representing the frequency of this translation pair in the data. The main purpose of this field is to provide a user interface with a means to sort back-translations so the most frequent terms are first. Required. "normalizedText": "str", # A string giving the normalized form of the source term that is a back-translation of the target. This value should be used as input to lookup examples. Required. "numExamples": 0 # An integer representing the number of examples that are available for this translation pair. Actual examples must be retrieved with a separate call to lookup examples. The number is mostly intended to facilitate display in a UX. For example, a user interface may add a hyperlink to the back-translation if the number of examples is greater than zero and show the back-translation as plain text if there are no examples. Note that the actual number of examples returned by a call to lookup examples may be less than numExamples, because additional filtering may be applied on the fly to remove "bad" examples. Required. } ], "confidence": 0.0, # A value between 0.0 and 1.0 which represents the "confidence" (or perhaps more accurately, "probability in the training data") of that translation pair. The sum of confidence scores for one source word may or may not sum to 1.0. Required. "displayTarget": "str", # A string giving the term in the target language and in a form best suited for end-user display. Generally, this will only differ from the normalizedTarget in terms of capitalization. For example, a proper noun like "Juan" will have normalizedTarget = "juan" and displayTarget = "Juan". Required. "normalizedTarget": "str", # A string giving the normalized form of this term in the target language. This value should be used as input to lookup examples. Required. "posTag": "str", # A string associating this term with a part-of-speech tag. Required. "prefixWord": "str" # A string giving the word to display as a prefix of the translation. Currently, this is the gendered determiner of nouns, in languages that have gendered determiners. For example, the prefix of the Spanish word "mosca" is "la", since "mosca" is a feminine noun in Spanish. This is only dependent on the translation, and not on the source. If there is no prefix, it will be the empty string. Required. } ] } ]
- 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]¶
Lookup Dictionary Examples.
Lookup Dictionary Examples.
- Parameters:
body (list[DictionaryExampleTextItem] or IO[bytes]) – Defines the content of the request. Is either a [DictionaryExampleTextItem] type or a IO[bytes] type. Required.
- Keyword Arguments:
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:
list of DictionaryExampleItem
- Return type:
- Raises:
Example
# 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(request: HttpRequest, *, stream: bool = False, **kwargs: Any) Awaitable[AsyncHttpResponse][source]¶
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
- Parameters:
request (HttpRequest) – The network request you want to make. Required.
- Keyword Arguments:
stream (bool) – Whether the response payload will be streamed. Defaults to False.
- Returns:
The response of your network call. Does not do error handling on your response.
- Return type:
- 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]¶
Translate Text.
Translate Text.
- Parameters:
body (list[InputTextItem] or IO[bytes]) – Defines the content of the request. Is either a [InputTextItem] type or a IO[bytes] type. Required.
- Keyword Arguments:
to_language (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_language (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.
- Returns:
list of TranslatedTextItem
- Return type:
- Raises:
Example
# response body for status code(s): 200 response == [ { "translations": [ { "text": "str", # A string giving the translated text. Required. "to": "str", # A string representing the language code of the target language. Required. "alignment": { "proj": "str" # Maps input text to translated text. The alignment information is only provided when the request parameter includeAlignment is true. Alignment is returned as a string value of the following format: [[SourceTextStartIndex]:[SourceTextEndIndex]"u2013[TgtTextStartIndex]:[TgtTextEndIndex]]. The colon separates start and end index, the dash separates the languages, and space separates the words. One word may align with zero, one, or multiple words in the other language, and the aligned words may be non-contiguous. When no alignment information is available, the alignment element will be empty. Required. }, "sentLen": { "srcSentLen": [ 0 # An integer array representing the lengths of the sentences in the input text. The length of the array is the number of sentences, and the values are the length of each sentence. Required. ], "transSentLen": [ 0 # An integer array representing the lengths of the sentences in the translated text. The length of the array is the number of sentences, and the values are the length of each sentence. Required. ] }, "transliteration": { "script": "str", # A string specifying the script used in the output. Required. "text": "str" # A string which is the result of converting the input string to the output script. Required. } } ], "detectedLanguage": { "language": "str", # A string representing the code of the detected language. Required. "score": 0.0 # A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence. Required. }, "sourceText": { "text": "str" # Input text in the default script of the source language. Required. } } ]
- 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]¶
Transliterate Text.
Transliterate Text.
- Parameters:
body (list[InputTextItem] or IO[bytes]) – Defines the content of the request. Is either a [InputTextItem] type or a IO[bytes] type. Required.
- Keyword Arguments:
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.
- Returns:
list of TransliteratedText
- Return type:
- Raises:
Example
# response body for status code(s): 200 response == [ { "script": "str", # A string specifying the script used in the output. Required. "text": "str" # A string which is the result of converting the input string to the output script. Required. } ]