Translator - Translate

Service:

Cognitive Services

API Version:

3.0

Translates text into one or more languages.

POST {Endpoint}/translate?api-version=3.0&to={to}

With optional parameters:

POST {Endpoint}/translate?api-version=3.0&from={from}&to={to}&textType={textType}&category={category}&profanityAction={profanityAction}&profanityMarker={profanityMarker}&includeAlignment={includeAlignment}&includeSentenceLength={includeSentenceLength}&suggestedFrom={suggestedFrom}&fromScript={fromScript}&toScript={toScript}

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints
api-version	query	True	string	Version of the API requested by the client. Value must be 3.0.
to	query	True	string[]	Specifies the language of the output text. Find which languages are available to translate to by using the languages method. For example, use to=de to translate to German. It's possible to translate to multiple languages simultaneously by repeating the to parameter in the query string. For example, use to=de&to=it to translate to German and Italian in the same request.
category	query		string	A string specifying the category (domain) of the translation. This parameter retrieves translations from a customized system built with Custom Translator. Default value is general.
from	query		string	Specifies the language of the input text. Find which languages are available to translate from by using the languages method. If the from parameter is not specified, automatic language detection is applied to determine the source language.
fromScript	query		string	Specifies the script of the input text. Supported scripts are available from the languages method
includeAlignment	query		boolean	Specifies whether to include alignment projection from source text to translated text. Possible values are- true or false (default).
includeSentenceLength	query		boolean	Specifies whether to include sentence boundaries for the input text and the translated text. Possible values are- true or false (default).
profanityAction	query		string	Specifies how profanities should be treated in translations. Possible values are: NoAction (default), Marked or Deleted. Handling Profanity Normally the Translator service will retain profanity that is present in the source in the translation. The degree of profanity and the context that makes words profane differ between cultures, and as a result the degree of profanity in the target language may be amplified or reduced. If you want to avoid getting profanity in the translation, regardless of the presence of profanity in the source text, you can use the profanity filtering option. The option allows you to choose whether you want to see profanity deleted, whether you want to mark profanities with appropriate tags (giving you the option to add your own post-processing), or you want no action taken. The accepted values of ProfanityAction are Deleted, Marked and NoAction (default). ProfanityAction Action NoAction This is the default behavior. Profanity will pass from source to target. Example Source (Japanese)- 彼はジャッカスです。 Example Translation (English)- He is a jackass. Deleted Profane words will be removed from the output without replacement. Example Source (Japanese)- 彼はジャッカスです。 Example Translation (English)- He is a. Marked Profane words are replaced by a marker in the output. The marker depends on the ProfanityMarker parameter. For ProfanityMarker=Asterisk, profane words are replaced with *** Example Source (Japanese)- 彼はジャッカスです。 Example Translation (English)- He is a ***. For ProfanityMarker=Tag, profane words are surrounded by XML tags and Example Source (Japanese)- 彼はジャッカスです。 Example Translation (English)- He is a jackass.
profanityMarker	query		string	Specifies how profanities should be marked in translations. Possible values are- Asterisk (default) or Tag.
suggestedFrom	query		string	Specifies a fallback language if the language of the input text can't be identified. Language auto-detection is applied when the from parameter is omitted. If detection fails, the suggestedFrom language will be assumed.
textType	query		string	Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete HTML element. Possible values are plain (default) or html
toScript	query		string[]	Specifies the script of the translated text. Supported scripts are available from the languages method

Request Header

Name	Required	Type	Description
X-ClientTraceId		string	A client-generated GUID to uniquely identify the request. Note that you can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

Request Body

Name	Type	Description
text	TranslateTextInput[]	Request body The body of the request is a JSON array. Each array element is a JSON object with a string property named Text, which represents the string to translate. The following limitations apply: The array can have at most 25 elements. The entire text included in the request cannot exceed 5,000 characters including spaces. Response body A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties- detectedLanguage- An object describing the detected language through the following properties. language- A string representing the code of the detected language. score- A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence. The detectedLanguage property is only present in the result object when language auto-detection is requested. translations- An array of translation results. The size of the array matches the number of target languages specified in the to query parameter. Each element in the array includes. to A string representing the language code of the target language. text- A string giving the translated text. transliteration- An object giving the translated text in the script specified by the toScript parameter. script- A string specifying the target script. text- A string giving the translated text in the target script. The transliteration object is not included if transliteration does not take place. *alignment- An object with a single string property named proj, which 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]–[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. See Obtain alignment information for an example and restrictions. sentLen- An object returning sentence boundaries in the input and output texts. srcSentLen- 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. transSentLen- 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. Sentence boundaries are only included when the request parameter includeSentenceLength is true. sourceText- An object with a single string property named text, which gives the input text in the default script of the source language. sourceText property is present only when the input is expressed in a script that's not the usual script for the language. For example, if the input were Arabic written in Latin script, then sourceText.text would be the same Arabic text converted into Arab script. Example of JSON responses are provided in the examples section.

Responses

Name	Type	Description
200 OK	TranslateResultAll[]	Success
Other Status Codes	ErrorMessage	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Ocp-Apim-Subscription-Region

Type: apiKey
In: header

Examples

Translate success example

Sample Request

HTTP

POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es&includeAlignment={includeAlignment}&includeSentenceLength={includeSentenceLength}&suggestedFrom={suggestedFrom}

[
  {
    "Text": "I would really like to drive your car."
  }
]

Sample Response

Status code:

200

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

Definitions

Name	Description
DetectedLanguage
Error
ErrorMessage
TranslateResultAll	Example of a successful translate request, including all optional parameters.
TranslateTextInput	Text needed for a translate request
Translations

DetectedLanguage

Name	Type	Description
language	string
score	integer

Error

Name	Type	Description
code	string
message	string

ErrorMessage

Name	Type	Description
error	Error

TranslateResultAll

Example of a successful translate request, including all optional parameters.

Name	Type	Description
detectedLanguage	DetectedLanguage
translations	Translations[]

TranslateTextInput

Text needed for a translate request

Name	Type	Description
text	string

Translations

Name	Type	Description
code	string
dir	string
name	string
nativeName	string