azure.ai.translation.text package¶

class azure.ai.translation.text.TextTranslationClient(*, credential: TokenCredential, 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.TextTranslationClient(*, credential: AzureKeyCredential, region: str | None = None, endpoint: str | None = None, api_version: str = '3.0', **kwargs)

class azure.ai.translation.text.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 + TokenCredential - 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 + TokenCredential - general translator endpoint with token authentication None + TokenCredential + 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, TokenCredential]) – 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.

close() → None[source]¶

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:

list[BreakSentenceItem]

Raises:

HttpResponseError –

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.
        }
    }
]

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, 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 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 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 (MatchConditions) – The match condition to use upon the etag. Default value is None.

Returns:

GetSupportedLanguagesResult. The GetSupportedLanguagesResult is compatible with MutableMapping

Return type:

GetSupportedLanguagesResult

Raises:

HttpResponseError –

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.
                        }
                    ]
                }
            ]
        }
    }
}

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.

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:

list[DictionaryLookupItem]

Raises:

HttpResponseError –

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.
            }
        ]
    }
]

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.

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:

list[DictionaryExampleItem]

Raises:

HttpResponseError –

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) → HttpResponse[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 = client.send_request(request)
<HttpResponse: 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:: HttpResponse

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:

list[TranslatedTextItem]

Raises:

HttpResponseError –

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.
        }
    }
]

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.

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:

list[TransliteratedText]

Raises:

HttpResponseError –

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.
    }
]

azure.ai.translation.text package¶

Subpackages¶