Microsoft Translator API INFO

Why should I use Custom Translator?

Get Better Translations

Use your previously translated documents (leaflets, webpages, documentation, etc.) to build a translation system that reflects your domain-specific terminology and style, better than a generic translation system. Users can upload TMX, XLIFF, TXT, DOCX, and XLSX documents.

To make data collection and preparation more effective, the system also accepts data that is parallel at the document level but is not yet aligned at the sentence level. If users have access to versions of the same content in multiple languages but in separate documents, Custom Translator will be able to automatically match sentences across documents. The system can also use monolingual data in either or both languages to complement the parallel training data to improve the translations.

Given the appropriate type and amount of training data it is not uncommon to expect gains between 5 and 10, or even more BLEU points on translation quality by using Custom Translator.

Be productive and cost effective

Training and deploying a custom system is easy and does not require any programming skills.

Using the secure Custom Translator portal, users can through an intuitive interface upload training data, train systems, test them right from the portal and deploy them to a production environment with a simple click. The system will then be available for use at scale within a few hours (actual time depends on training data size).

Custom Translator can also be programmatically accessed through a dedicated API. This allows users that create or update training on a regular basis to manage these processes through their own app or webservice.

While in Preview, there is no charge to train or deploy custom models. Once deployed, the cost of using a custom model to translate content is based on the subscriber’s Translator Text API pricing tier.

Pricing for Custom Translator, when in General Availability, will be based on the subscriber’s Translator Text API pricing tier.

• Training a custom system is 1 character per character of training material in source text.
• Hosting a deployed system is 1M characters per month per deployed system.
• The cost of using a deployed customized translation system is the same as the un-customized systems, which is based on the subscriber’s Translator Text API pricing tier.

Securely translate anytime, anywhere on all your apps and services

Translation systems built with Custom Translator are available through the same cloud-based, high performance, highly scalable Microsoft Translator API that powers billions of translations every day. Custom systems can be seamlessly accessed and integrated into any product or business workflow, and on any device, via the Microsoft Translator API or the Cognitive Services Speech preview, through standard REST technology.

---

How do I get started?

1. Ensure you have a Translator text API key
If you don’t have a key already, learn how to sign up

2. Watch the how to video and read the user guide
The video below will give you a quick overview for how to use Custom Translator and the Custom Translator user guide will teach you everything you need to know to start customizing your translations

3. Log into the Custom Translator portal
You can use your Microsoft account or corporate email to sign into the portalâ

General

See the language list for both the Microsoft Translator Text API and the Translator Speech API.

Developer oriented language lists, including language codes can be found in our documentation.

Language lists for consumer apps can be found on our consumer website.

Microsoft Translator, part of the collection of Cognitive Services and an Azure service, is a cloud-based API offering two sets of APIs – Translator Text API and Translator Speech API.

The Microsoft Translator Text API supports text translation and text-to-speech automatically translates between any of the more than 60 supported languages.

Additional functionality includes language detection, transliteration, bilingual dictionary, and customization with the Custom Translator (Preview).

The Microsoft Translator Speech API is the world’s first end-to-end speech translation API and supports both speech-to-speech and speech-to-text translation.

It is the same API that powers the speech translation capabilities in the Presentation Translator, Microsoft Translator live feature, Skype Translator, and the conversation feature of the Microsoft Translator iOS and Android apps.

Absolutely. Microsoft Translator offers a subscription plan in the Azure portal at no charge. The Microsoft Translator Text and Speech APIs are available in the Cognitive Services section of the Azure portal. The subscription is self-managed and you change the monthly subscription plan as needed.

New Azure portal users can sign up for a free 30-day Azure Account, which includes a $200 USD credit to spend towards any Azure service, which includes the Microsoft Translator API.

For the Microsoft Translator Text API, the volume you are billed for is the number of characters in the input. Every Unicode code point counts as a character. Every character of the input counts. Each translation of a text to a new language counts as a separate translation. The number of queries, words, bytes, or sentences is irrelevant.

What counts is:

• Text you pass into the Translate, TranslateArray, TranslateArray2, GetTranslations, GetTranslationsArray, Dictionary, Transliterate and TransformText method
• A repeated translation, even if you have translated the same text previously
• All markup: HTML, XML tags, etc.
• An individual letter
• A space, tab, markup, and any kind of white space character
• Every code point defined in Unicode

To estimate your monthly volume, take the total characters to translate, multiply it by the number of languages you want to have it translated into, then take the number and spread it over the maximum number of hours or days you are able to wait for completion.

As an order of magnitude, this FAQ contains about 6,000 characters; a 30-page document has around 17,000 characters; the seven Harry Potter books comprise about 60 million characters.

More information on how we count characters for the Translator Text API can be found in our documentation.

For the Microsoft Translator Speech Translation API, all of the audio data (in seconds of audio), including silence, submitted to the Microsoft Translator service counts towards the subscribed monthly transaction balance.

For the new Microsoft Speech services (Preview), see the pricing page.

The Microsoft Translator API is available on the Azure portal. Payment is by credit or debit cards only, unless previously approved for invoice.

For enterprise customers who qualify for an Enterprise Agreement (EA) in the Microsoft Volume Licensing Program, please inquire through your company’s procurement department. The Microsoft Translator API can be added to the EA at any time. There are two separate Microsoft Translator API offers.

Translator Text API

Translator Speech API

Microsoft Speech services (Preview)

Pricing is based on your Azure monthly subscription period and you will automatically be billed every month until you cancel the Microsoft Translator API subscription.

Yes, Microsoft Translator gives users the ability to customize translations:

Build a custom language model based on your pre-existing translated text that reflects your domain, terminology or style using Custom Translator (Preview). Learn more

You can monitor, view metrics and add Azure alerts for your Azure services in your user account on Azure. Read more in the sources of monitoring data in Microsoft Azure.

Microsoft Translator supported business products are listed in the “Products” menu item above.

End user apps can be viewed here.

Yes, the Microsoft Translator attribution is required when using the Microsoft Translator API – Text Translation and Speech Translation. Follow the requirements outlined in the Microsoft Translator attribution guidelines.

Microsoft takes your privacy seriously. Please read the full Microsoft Translator privacy statement.

When connecting to the service, customers can use the unencrypted, http:// protocol or the https://, SSL-encrypted protocol. The latter uses a 2,048-bit RSA key and the implementation is not linked, and therefore not susceptible to the security risks of Open SSL.

Microsoft Translator follows the GDPR processor commitment. We support your GDPR compliance via new controls. Learn more about GDPR

No. Machine translation is generally used where the quality-level requirement is not as stringent as where human translation is required. Use machine translation where the quantity of content, speed of content creation (such as user-generated content in blogs, forums, etc.), and budget (or lack thereof) make it impossible to use human translation. It caters to a segment of the market for translation needs that, thus far, could not be made economically feasible or could not be made available with a very short turnaround time.

Machine translation has been used as a first pass by several of our language service provider (LSP) partners, before using human translation; it can improve productivity by up to 50 percent. For a list of LSPs, please visit the Microsoft Translator partner page.

Microsoft Translator evaluates the quality with the BLEU (bilingual evaluation understudy) standards and our own benchmarks (both automatic and human evaluations). We are constantly improving our machine-learning engines and language models.

Depending on multiple variables, such as length and type of text translated, language pairs (source and target), industry lingo, or the domain in which Translator is used, results will vary greatly for any vendor offering a machine translation solution.

When you select the “in school” option the session will default to a locked “Presentation” mode, where only the creator of the conversation can speak, and everyone else is in “listen” mode. This setting is available to protect children’s privacy as per COPPA regulations as the spoken conversation is recorded for product improvement purposes.

Yes, Translator can be used with the Microsoft Bot Framework to create interactive multilingual bots. You can use bots to facilitate and streamline activities such as international customer support and internal readiness. View Translator code samples in the Bot SDK v4 preview library on GitHub at www.aka.ms/Translatorforbots

Learn more about Microsoft’s Bot Framework at dev.botframework.com.

We have a few resources available at no charge:

• Microsoft Translator Text API and Speech API documentation
• Example apps on GitHub
• Microsoft Translator API and UserVoice Cognitive Services Knowledge Base articles
• You may also find answers online either through our website or through the Microsoft Translator user and developer forum

---

Development

Go to docs.microsoft.com/en-us/azure/cognitive-services. Example apps are available on GitHub.

For the Microsoft Translator Text API, access is via REST. For the Microsoft Translator Speech API, access is via REST, WebSocket.

---

Subscriptions

No, you will automatically be renewed at the current pricing every month until you change or cancel the subscription. You are billed at the end of a subscription month.

If you subscribe to the free subscription plan, the Microsoft Translator service will stop if you reach 2 million characters during a subscription month for the Text Translation API, and 10 hours if you are subscribed to the Speech Translation API. The Microsoft Translator service will start again at the beginning of your next subscription month or when you change your subscription to a paid plan.

See the pricing details for the unified Speech services (Preview)

The characters left over in a subscription month are lost, there are no remaining balance rollovers, credits or refunds.

Yes, and you will lose any remaining balance in the plan when you change plans. Also, at the end of each subscription month, you will lose any remaining balance you have in the current subscription.

---

Support

We have a few resources available at no charge:

• Microsoft Translator API documentation
• Example apps are available on GitHub
• Microsoft Translator API and Translator Hub UserVoice Cognitive Services Knowledge Base articles
• You may find answers online either through our website or through the Microsoft Translator user and developer forum

Please check the above resources first; if you don’t find an answer, post your question on the forum. For questions related to an error, please include the time the error occurred (including the time zone), the date, a copy of the error message, and a snippet of the code.

Visit the Azure billing and subscription FAQ webpage first and if you need immediate assistance, log into your user account in the Azure portal and click on the ‘Help + Support’ icon at the top right corner of the webpage to submit a support request.

Translator Text API Documentation

Microsoft Translator Text API is a cloud-based machine translation service. With this API you can translate text in near real-time from any app or service through a simple REST API call. The API uses the most modern neural machine translation technology, as well as offering statistical machine translation technology. For the list of supported languages, both for neural MT and statistical MT, please refer to Supported languages.

Step-by-Step Tutorials Learn how to develop applications using the Translator Text API:
Write a WPF application for Translator Text using C#

Reference

API Reference

Translator Text API v3.0

• 03/29/2018
• 2 minutes to read
• Contributors
  • 
  • 

What's new?

Version 3 of the Microsoft Translator Text API provides a modern JSON-based Web API. It improves usability and performance by consolidating existing features into fewer operations and it provides new features.

• Transliteration to convert text in one language from one script to another script.
• Translation to multiple languages in one request.
• Language detection, translation, and transliteration in one request.
• Dictionary to lookup alternative translations of a term, to find back-translations and examples showing terms used in context.
• More informative language detection results.

Base URLs

Text API v3.0 is available in the following cloud:

Description	Region	Base URL
Azure	Global	api.cognitive.microsofttranslator.com

Authentication

Subscribe to Translator Text API in Microsoft Cognitive Services and use your subscription key (available in the Azure portal) to authenticate.
The simplest way is to pass your Azure secret key to the Translator service using request header Ocp-Apim-Subscription-Key.
An alternative is to use your secret key to obtain an authorization token from the token service. Then, you pass the authorization token to the Translator service using the Authorization request header. To obtain an authorization token, make a POST request to the following URL:

Environment	Authentication service URL
Azure	https://api.cognitive.microsoft.com/sts/v1.0/issueToken

Here are example requests to obtain a token given a secret key:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'
// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

A successful request returns the encoded access token as plain text in the response body. The valid token is passed to the Translator service as a bearer token in the Authorization.

Authorization: Bearer <Base64-access_token>

An authentication token is valid for 10 minutes. The token should be re-used when making multiple calls to the Translator APIs. However, if your program makes requests to the Translator API over an extended period of time, then your program must request a new access token at regular intervals (e.g. every 8 minutes).
To summarize, a client request to the Translator API will include one authorization header taken from the following table:

Headers	Description
Ocp-Apim-Subscription-Key	Use with Cognitive Services subscription if you are passing your secret key. The value is the Azure secret key for your subscription to Translator Text API.
Authorization	Use with Cognitive Services subscription if you are passing an authentication token. The value is the Bearer token: Bearer <token>.

Errors

A standard error response is a JSON object with name/value pair named error. The value is also a JSON object with properties:

• code: A server-defined error code.
  
• message: A string giving a human-readable representation of the error.
  

For example, a customer with a free trial subscription would receive the following error once the free quota is exhausted:

{
  "error": {
    "code":403000,
    "message":"The subscription has exceeded its free quota."
    }
}

Gets the set of languages currently supported by other operations of the Text API.

Request URL

Send a GET request to:

HTTP

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be 3.0.
scope	Optional parameter. 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.

Request headers are:

Headers	Description
Accept-Language	Optional request header. 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.
X-ClientTraceId	Optional request header. A client-generated GUID to uniquely identify the request.

Authentication isn't required to get language resources.

Response body

A client uses the scope query parameter to define which groups of languages it's interested in.

• scope=translation provides languages supported to translate text from one language to another language;
  
• scope=transliteration provides capabilities for converting text in one language from one script to another script;
  
• scope=dictionary provides language pairs for which Dictionary operations return data.
  

A client may retrieve several groups simultaneously by specifying a comma-separated list of names. For example, scope=translation,transliteration,dictionary would return supported languages for all groups.
A successful response is a JSON object with one property for each requested group:

JSON

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

The value for each property is as follows.

• translation property
  The value of the translation property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A key identifies a language for which text can be translated to or translated from. The value associated with the key is a JSON object with properties that describe the language:
  
  • name: Display name of the language in the locale requested via Accept-Language header.
    
  • nativeName: Display name of the language in the locale native for this language.
    
  • dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.
    
  An example is:
  
  JSON

{
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

transliteration property  The value of the transliteration property is a  dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A  key identifies a language for which text can be converted from one  script to another script. The value associated with the key is a JSON  object with properties that describe the language and its supported  scripts:  
name: Display name of the language in the locale requested via Accept-Language header.  
nativeName: Display name of the language in the locale native for this language.  
scripts: List of scripts to convert from. Each element of the scripts list has properties:  
code: Code identifying the script.  
name: Display name of the script in the locale requested via Accept-Language header.  
nativeName: Display name of the language in the locale native for the language.  
dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.  
toScripts: List of scripts available to convert text to. Each element of the toScripts list has properties code, name, nativeName, and dir as described earlier.  

An example is:  
JSON    
{
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr"
            }
          ]
        }
      ]
    },
    ...
  }
}

dictionary property  The value of the dictionary property is a dictionary of  (key, value) pairs. Each key is a BCP 47 language tag. The key  identifies a language for which alternative translations and  back-translations are available. The value is a JSON object that  describes the source language and the target languages with available  translations:  
name: Display name of the source language in the locale requested via Accept-Language header.  
nativeName: Display name of the language in the locale native for this language.  
dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.  
translations: List of languages with alterative  translations and examples for the query expressed in the source  language. Each element of the translations list has properties:  
name: Display name of the target language in the locale requested via Accept-Language header.  
nativeName: Display name of the target language in the locale native for the target language.  
dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.  
code: Language code identifying the target language.  

An example is:  
JSON    
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

The structure of the response object will not change without a change
 in the version of the API. For the same version of the API, the list of
 available languages may change over time because Microsoft Translator 
continually extends the list of languages supported by its services.
The list of supported languages will not change frequently. To save 
network bandwidth and improve responsiveness, a client application 
should consider caching language resources and the corresponding entity 
tag (ETag). Then, the client application can periodically 
(for example, once every 24 hours) query the service to fetch the latest
 set of supported languages. Passing the current ETag value in an If-None-Match
 header 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.
Response headers

Headers
   
Description
   
     
ETag
     
Current value of the entity tag for the requested groups of  supported languages. To make subsequent requests more efficient, the  client may send the ETag value in an If-None-Match header field.     
   
     
X-RequestId
     
Value generated by the service to identify the request. It is used for troubleshooting purposes.
   
Response status codes
The following are the possible HTTP status codes that a request returns. 

Status Code
   
Description
   
     
200
     
Success.
   
     
304
     
The resource has not been modified since the version specified by request headers If-None-Match.
   
     
400
     
One of the query parameters is missing or not valid. Correct request parameters before retrying.
   
     
429
     
The caller is sending too many requests.
   
     
500
     
An unexpected error occurred. If the error persists, report it  with: date and time of the failure, request identifier from response  header X-RequestId, and client identifier from request header X-ClientTraceId.
   
     
503
     
Server temporarily unavailable. Retry the request. If the error  persists, report it with: date and time of the failure, request  identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
   
Examples
The following example shows how to retrieve languages supported for text translation.
 curl 


   
curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"

Text API 3.0: Translate

• 03/29/2018
• 11 minutes to read
• Contributors
  • 
  • 

Translates text.

Request URL

Send a POST request to:

HTTP

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be 3.0.
from	Optional parameter. 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 is not specified, automatic language detection is applied to determine the source language.
to	Required parameter. 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.
textType	Optional parameter. 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.
category	Optional parameter. A string specifying the category (domain) of the translation. This parameter is used to get translations from a customized system built with Custom Translator. Default value is: general.
profanityAction	Optional parameter. Specifies how profanities should be treated in translations. Possible values are: NoAction (default), Marked or Deleted. To understand ways to treat profanity, see Profanity handling.
profanityMarker	Optional parameter. Specifies how profanities should be marked in translations. Possible values are: Asterisk (default) or Tag. To understand ways to treat profanity, see Profanity handling.
includeAlignment	Optional parameter. Specifies whether to include alignment projection from source text to translated text. Possible values are: true or false (default).
includeSentenceLength	Optional parameter. Specifies whether to include sentence boundaries for the input text and the translated text. Possible values are: true or false (default).
suggestedFrom	Optional parameter. 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.
fromScript	Optional parameter. Specifies the script of the input text.
toScript	Optional parameter. Specifies the script of the translated text.

Request headers include:

Headers	Description
One authorization header	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: application/json.
Content-Length	Required request header. The length of the request body.
X-ClientTraceId	Optional. A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

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.

JSON

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

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 through 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.

Response status codes

The following are the possible HTTP status codes that a request returns.

Status Code	Description
200	Success.
400	One of the query parameters is missing or not valid. Correct request parameters before retrying.
401	The request could not be authenticated. Check that credentials are specified and valid.
403	The request is not authorized. Check the details error message. This often indicates that all free translations provided with a trial subscription have been used up.
429	The caller is sending too many requests.
500	An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503	Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

Examples

Translate a single input

This example shows how to translate a single sentence from English to Simplified Chinese.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

The response body is:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

The translations array includes one element, which provides the translation of the single piece of text in the input.

Translate a single input with language auto-detection

This example shows how to translate a single sentence from English to Simplified Chinese. The request does not specify the input language. Auto-detection of the source language is used instead.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

The response body is:

[
    {
        "detectedLanguage": {"language": "en", "score": 1.0},
        "translations":[
            {"text": "你好, 你叫什么名字？", "to": "zh-Hans"}
        ]
    }
]

The response is similar to the response from the previous example. Since language auto-detection was requested, the response also includes information about the language detected for the input text.

Translate with transliteration

Let's extend the previous example by adding transliteration. The following request asks for a Chinese translation written in Latin script.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

The response body is:

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"text":"nǐ hǎo , nǐ jiào shén me míng zì ？","script":"Latn"},
                "to":"zh-Hans"
            }
        ]
    }
]

The translation result now includes a transliteration property, which gives the translated text using Latin characters.

Translate multiple pieces of text

Translating multiple strings at once is simply a matter of specifying an array of strings in the request body.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

The response body is:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },            
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Translate to multiple languages

This example shows how to translate the same input to several languages in one request.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

The response body is:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Handle 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 <profanity> and </profanity>: Example Source (Japanese): 彼はジャッカスです。 Example Translation (English): He is a <profanity>jackass</profanity>.

For example:

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'This is a fucking good idea.'}]"

This returns:

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Compare with:

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'This is a fucking good idea.'}]"

That last request returns:

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Translate content with markup and decide what's translated

It's common to translate content which includes markup such as content from an HTML page or content from an XML document. Include query parameter textType=html when translating content with tags. In addition, it's sometimes useful to exclude specific content from translation. You can use the attribute class=notranslate to specify content that should remain in its original language. In the following example, the content inside the first div element will not be translated, while the content in the second div element will be translated.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Here is a sample request to illustrate.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

The response is:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Obtain alignment information

To receive alignment information, specify includeAlignment=true on the query string.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'The answer lies in machine translation.'}]"

The response is:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

The alignment information starts with 0:2-0:1, which means that the first three characters in the source text (The) map to the first two characters in the translated text (La).
Note the following restrictions:

• Alignment is only returned for a subset of the language pairs:
  • from English to any other language;
  • from any other language to English except for Chinese Simplified, Chinese Traditional, and Latvian to English;
  • from Japanese to Korean or from Korean to Japanese.
• You will not receive alignment if the sentence is a canned translation. Example of a canned translation is "This is a test", "I love you" and other high frequency sentences.

Obtain sentence boundaries

To receive information about sentence length in the source text and translated text, specify includeSentenceLength=true on the query string.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

The response is:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n’importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

Translate with dynamic dictionary

If you already know the translation you want to apply to a word or a phrase, you can supply it as markup within the request. The dynamic dictionary is only safe for compound nouns like proper names and product names.
The markup to supply uses the following syntax.

<mstrans:dictionary translation=”translation of phrase”>phrase</mstrans:dictionary>

For example, consider the English sentence "The word wordomatic is a dictionary entry." To preserve the word wordomatic in the translation, send the request:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

The result is:

[
    {
        "translations":[
            {"text":"Das Wort "wordomatic" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

This feature works the same way with textType=text or with textType=html. The feature should be used sparingly. The appropriate and far better way of customizing translation is by using Custom Translator. Custom Translator makes full use of context and statistical probabilities. If you have or can afford to create training data that shows your work or phrase in context, you get much better results. Learn more about Custom Translator.

Text API 3.0: Transliterate

• 03/29/2018
• 2 minutes to read
• Contributors
  • 
  • 

Converts text in one language from one script to another script.

Request URL

Send a POST request to:

HTTP

https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be 3.0.
language	Required parameter. 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.
fromScript	Required parameter. Specifies the script used by the input text. Lookup supported languages using the transliteration scope, to find input scripts available for the selected language.
toScript	Required parameter. Specifies the output script. Lookup supported languages using the transliteration scope, to find output scripts available for the selected combination of input language and input script.

Request headers include:

Headers	Description
One authorization header	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: application/json.
Content-Length	Required request header. The length of the request body.
X-ClientTraceId	Optional. 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

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 convert.

JSON

[
    {"Text":"こんにちは"},
    {"Text":"さようなら"}
]

The following limitations apply:

• The array can have at most 10 elements.
• The text value of an array element cannot exceed 1,000 characters including spaces.
• 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 element in the input array. A result object includes the following properties:

• text: A string which is the result of converting the input string to the output script.
  
• script: A string specifying the script used in the output.
  

An example JSON response is:

JSON

[
    {"text":"konnnichiha","script":"Latn"},
    {"text":"sayounara","script":"Latn"}
]

Response headers

Headers	Description
X-RequestId	Value generated by the service to identify the request. It is used for troubleshooting purposes.

Response status codes

The following are the possible HTTP status codes that a request returns.

Status Code	Description
200	Success.
400	One of the query parameters is missing or not valid. Correct request parameters before retrying.
401	The request could not be authenticated. Check that credentials are specified and valid.
403	The request is not authorized. Check the details error message. This often indicates that all free translations provided with a trial subscription have been used up.
429	The caller is sending too many requests.
500	An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503	Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

Examples

The following example shows how to convert two Japanese strings into Romanized Japanese.

• curl

The JSON payload for the request in this example:

[{"text":"こんにちは","script":"jpan"},{"text":"さようなら","script":"jpan"}]

If you are using cUrl in a command-line window that does not support Unicode characters, take the following JSON payload and save it into a file named request.txt. Be sure to save the file with UTF-8 encoding.

curl -X POST "https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d @request.txt

Text API 3.0: Detect

• 03/29/2018
• 2 minutes to read
• Contributors
  • 
  • 

Identifies the language of a piece of text.

Request URL

Send a POST request to:

HTTP

https://api.cognitive.microsofttranslator.com/detect?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be 3.0.

Request headers include:

Headers	Description
One authorization header	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: application/json.
Content-Length	Required request header. The length of the request body.
X-ClientTraceId	Optional. 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

The body of the request is a JSON array. Each array element is a JSON object with a string property named Text. Language detection is applied to the value of the Text property. A sample request body looks like that:

JSON

[
    { "Text": "Ich würde wirklich gern Ihr Auto um den Block fahren ein paar Mal." }
]

The following limitations apply:

• The array can have at most 100 elements.
• The text value of an array element cannot exceed 10,000 characters including spaces.
• The entire text included in the request cannot exceed 50,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:

• language: 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.
  
• isTranslationSupported: A boolean value which is true if the detected language is one of the languages supported for text translation.
  
• isTransliterationSupported: A boolean value which is true if the detected language is one of the languages supported for transliteration.
  
• alternatives: An array of other possible languages. Each element of the array is another object with the same properties listed above: language, score, isTranslationSupported and isTransliterationSupported.
  

An example JSON response is:

JSON

[
  {
    "language": "de",
    "score": 0.92,
    "isTranslationSupported": true,
    "isTransliterationSupported": false,
    "alternatives": [
      {
        "language": "pt",
        "score": 0.23,
        "isTranslationSupported": true,
        "isTransliterationSupported": false
      },
      {
        "language": "sk",
        "score": 0.23,
        "isTranslationSupported": true,
        "isTransliterationSupported": false
      }
    ]
  }
]

Response headers

Headers	Description
X-RequestId	Value generated by the service to identify the request. It is used for troubleshooting purposes.

Response status codes

The following are the possible HTTP status codes that a request returns.

Status Code	Description
200	Success.
400	One of the query parameters is missing or not valid. Correct request parameters before retrying.
401	The request could not be authenticated. Check that credentials are specified and valid.
403	The request is not authorized. Check the details error message. This often indicates that all free translations provided with a trial subscription have been used up.
429	The caller is sending too many requests.
500	An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503	Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

Examples

The following example shows how to retrieve languages supported for text translation.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/detect?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'What language is this text written in?'}]"

Text API 3.0: BreakSentence

• 03/29/2018
• 3 minutes to read
• Contributors
  • 
  • 

Identifies the positioning of sentence boundaries in a piece of text.

Request URL

Send a POST request to:

HTTP

https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required query parameter. Version of the API requested by the client. Value must be 3.0.
language	Optional query parameter. Language tag identifying the language of the input text. If a code is not specified, automatic language detection will be applied.
script	Optional query parameter. Script tag identifying the script used by the input text. If a script is not specified, the default script of the language will be assumed.

Request headers include:

Headers	Description
One authorization header	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: application/json.
Content-Length	Required request header. The length of the request body.
X-ClientTraceId	Optional. 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

The body of the request is a JSON array. Each array element is a JSON object with a string property named Text. Sentence boundaries are computed for the value of the Text property. A sample request body with one piece of text looks like that:

JSON

[
    { "Text": "How are you? I am fine. What did you do today?" }
]

The following limitations apply:

• The array can have at most 100 elements.
• The text value of an array element cannot exceed 10,000 characters including spaces.
• The entire text included in the request cannot exceed 50,000 characters including spaces.
• If the language query parameter is specified, then all array elements must be in the same language. Otherwise, language auto-detection is applied to each array element independently.

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:

• sentLen: An array of integers representing the lengths of the sentences in the text element. The length of the array is the number of sentences, and the values are the length of each sentence.
  
• detectedLanguage: An object describing the detected language through the following properties:
  
  • language: 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.
    
  Note that the detectedLanguage property is only present in the result object when language auto-detection is requested.
  

An example JSON response is:

JSON

[
  {
    "sentenceLengths": [ 13, 11, 22 ]
    "detectedLanguage": {
      "language": "en",
      "score": 401
    },
  }
]

Response headers

Headers	Description
X-RequestId	Value generated by the service to identify the request. It is used for troubleshooting purposes.

Response status codes

The following are the possible HTTP status codes that a request returns.

Status Code	Description
200	Success.
400	One of the query parameters is missing or not valid. Correct request parameters before retrying.
401	The request could not be authenticated. Check that credentials are specified and valid.
403	The request is not authorized. Check the details error message. This often indicates that all free translations provided with a trial subscription have been used up.
429	The caller is sending too many requests.
500	An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503	Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

Examples

The following example shows how to obtain sentence boundaries for a single sentence. The language of the sentence is automatically detected by the service.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'How are you? I am fine. What did you do today?'}]"

Text API 3.0: Dictionary Lookup

• 03/29/2018
• 5 minutes to read
• Contributors
  • 
  • 
  • 

Provides alternative translations for a word and a small number of idiomatic phrases. Each translation has a part-of-speech and a list of back-translations. The back-translations enable a user to understand the translation in context. The Dictionary Example operation allows further drill down to see example uses of each translation pair.

Request URL

Send a POST request to:

HTTP

https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be 3.0.
from	Required parameter. Specifies the language of the input text. The source language must be one of the supported languages included in the dictionary scope.
to	Required parameter. Specifies the language of the output text. The target language must be one of the supported languages included in the dictionary scope.

Request headers include:

Headers	Description
One authorization header	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: application/json.
Content-Length	Required request header. The length of the request body.
X-ClientTraceId	Optional. A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

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 term to lookup.

JSON

[
    {"Text":"fly"}
]

The following limitations apply:

• The array can have at most 10 elements.
• The text value of an array element cannot exceed 100 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:

• normalizedSource: 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.
  
• displaySource: 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".
  
• translations: A list of translations for the source term. Each element of the list is an object with the following properties:
  
  • normalizedTarget: A string giving the normalized form of this term in the target language. This value should be used as input to lookup examples.
    
  • displayTarget: 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".
    
  • posTag: A string associating this term with a part-of-speech tag.
    

    Tag name	Description
    ADJ	Adjectives
    ADV	Adverbs
    CONJ	Conjunctions
    DET	Determiners
    MODAL	Verbs
    NOUN	Nouns
    PREP	Prepositions
    PRON	Pronouns
    VERB	Verbs
    OTHER	Other

    As an implementation note, these tags were determined by part-of-speech tagging the English side, and then taking the most frequent tag for each source/target pair. So if people frequently translate a Spanish word to a different part-of-speech tag in English, tags may end up being wrong (with respect to the Spanish word).
    
  • confidence: 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.
    
  • prefixWord: 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.
    
  • backTranslations: A list of "back translations" of the target. For example, source words that the target can translate to. The list is guaranteed to contain the source word that was requested (e.g., if the source word being looked up is "fly", then it is guaranteed that "fly" will be in the backTranslations list). However, it is not guaranteed to be in the first position, and often will not be. Each element of the backTranslations list is an object described by the following properties:
    
    • normalizedText: 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.
      
    • displayText: A string giving the source term that is a back-translation of the target in a form best suited for end-user display.
      
    • numExamples: 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.
      
    • frequencyCount: 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.
      
  Note
  If the term being looked-up does not exist in the dictionary, the response is 200 (OK) but the translations list is an empty list.

Examples

This example shows how to lookup alternative translations in Spanish of the English term fly .

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0&from=en&to=es" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly'}]"

The response body (abbreviated for clarity) is:

[
    {
        "normalizedSource":"fly",
        "displaySource":"fly",
        "translations":[
            {
                "normalizedTarget":"volar",
                "displayTarget":"volar",
                "posTag":"VERB",
                "confidence":0.4081,
                "prefixWord":"",
                "backTranslations":[
                    {"normalizedText":"fly","displayText":"fly","numExamples":15,"frequencyCount":4637},
                    {"normalizedText":"flying","displayText":"flying","numExamples":15,"frequencyCount":1365},
                    {"normalizedText":"blow","displayText":"blow","numExamples":15,"frequencyCount":503},
                    {"normalizedText":"flight","displayText":"flight","numExamples":15,"frequencyCount":135}
                ]
            },
            {
                "normalizedTarget":"mosca",
                "displayTarget":"mosca",
                "posTag":"NOUN",
                "confidence":0.2668,
                "prefixWord":"",
                "backTranslations":[
                    {"normalizedText":"fly","displayText":"fly","numExamples":15,"frequencyCount":1697},
                    {"normalizedText":"flyweight","displayText":"flyweight","numExamples":0,"frequencyCount":48},
                    {"normalizedText":"flies","displayText":"flies","numExamples":9,"frequencyCount":34}
                ]
            },
            //
            // ...list abbreviated for documentation clarity
            //
        ]
    }
]

This example shows what happens when the term being looked up does not exist for the valid dictionary pair.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0&from=en&to=es" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly123456'}]"

Since the term is not found in the dictionary, the response body includes an empty translations list.

[
    {
        "normalizedSource":"fly123456",
        "displaySource":"fly123456",
        "translations":[]
    }
]

Text API 3.0: Dictionary Examples

• 03/29/2018
• 3 minutes to read
• Contributors
  • 
  • 

Provides examples that show how terms in the dictionary are used in context. This operation is used in tandem with Dictionary lookup.

Request URL

Send a POST request to:

HTTP

https://api.cognitive.microsofttranslator.com/dictionary/examples?api-version=3.0

Request parameters

Request parameters passed on the query string are:

Query parameter	Description
api-version	Required parameter. Version of the API requested by the client. Value must be 3.0.
from	Required parameter. Specifies the language of the input text. The source language must be one of the supported languages included in the dictionary scope.
to	Required parameter. Specifies the language of the output text. The target language must be one of the supported languages included in the dictionary scope.

Request headers include:

Headers	Description
One authorization header	Required request header. See available options for authentication.
Content-Type	Required request header. Specifies the content type of the payload. Possible values are: application/json.
Content-Length	Required request header. The length of the request body.
X-ClientTraceId	Optional. A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

Request body

The body of the request is a JSON array. Each array element is a JSON object with the following properties:

• Text: A string specifying the term to lookup. This should be the value of a normalizedText field from the back-translations of a previous Dictionary lookup request. It can also be the value of the normalizedSource field.
  
• Translation: A string specifying the translated text previously returned by the Dictionary lookup operation. This should be the value from the normalizedTarget field in the translations list of the Dictionary lookup response. The service will return examples for the specific source-target word-pair.
  

An example is:

JSON

[
    {"Text":"fly", "Translation":"volar"}
]

The following limitations apply:

• The array can have at most 10 elements.
• The text value of an array element cannot exceed 100 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:

• normalizedSource: 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.
  
• normalizedTarget: 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.
  
• examples: A list of examples for the (source term, target term) pair. Each element of the list is an object with the following properties:
  
  • sourcePrefix: 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.
    
  • sourceTerm: 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.
    
  • sourceSuffix: 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.
    
  • targetPrefix: A string similar to sourcePrefix but for the target.
    
  • targetTerm: A string similar to sourceTerm but for the target.
    
  • targetSuffix: A string similar to sourceSuffix but for the target.
    
  Note
  If there are no examples in the dictionary, the response is 200 (OK) but the examples list is an empty list.

Examples

This example shows how to lookup examples for the pair made up of the English term fly and its Spanish translation volar.

• curl

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/examples?api-version=3.0&from=en&to=es" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly', 'Translation':'volar'}]"

The response body (abbreviated for clarity) is:

[
    {
        "normalizedSource":"fly",
        "normalizedTarget":"volar",
        "examples":[
            {
                "sourcePrefix":"They need machines to ",
                "sourceTerm":"fly",
                "sourceSuffix":".",
                "targetPrefix":"Necesitan máquinas para ",
                "targetTerm":"volar",
                "targetSuffix":"."
            },      
            {
                "sourcePrefix":"That should really ",
                "sourceTerm":"fly",
                "sourceSuffix":".",
                "targetPrefix":"Eso realmente debe ",
                "targetTerm":"volar",
                "targetSuffix":"."
            },
            //
            // ...list abbreviated for documentation clarity
            //
        ]
    }
]

**********

Translator Text API v2.0

• 05/15/2018
• 29 minutes to read
• Contributors
  • 

Important
This version of the Translator Text API has been deprecated. View documentation for v3 of the Translator Text API.

Microsoft Translator V2 Text API can be seamlessly integrated into your applications, websites, tools, or other solutions to provide multi-language user experiences. Leveraging industry standards, it can be used on any hardware platform and with any operating system to perform language translation and other language-related operations such as text language detection or text to speech. Click Here for more information about the Microsoft Translator API.

Getting started

To access the Microsoft Translator Text API you will need to sign up for Microsoft Azure.

Authorization

All calls to Microsoft Translator Text API require a subscription key to authenticate. The API supports two modes of authentication:

• Using an access token. Use the subscription key referenced in step 9 to generate an access token by making a POST request to the authorization service. See the token service documentation for details. Pass the access token to the Translator service using the Authorization header or the access_token query parameter. The access token is valid for 10 minutes. Obtain a new access token every 10 minutes, and keep using the same access token for repeated requests within these 10 minutes.
  
• Using a subscription key directly. Pass your subscription key as a value in Ocp-Apim-Subscription-Key header included with your request to the Translator API. In this mode, you do not have to call the authentication token service to generate an access token.
  

Consider your subscription key and the access token as secrets that should be hidden from view.

Profanity handling

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 for the methods that support it. The option allows you to choose whether you want to see profanity deleted or marked with appropriate tags, or no action taken. The accepted values of ProfanityAction are NoAction (default), Marked and Deleted.

ProfanityAction	Action	Example Source (Japanese)	Example Translation (English)
NoAction	Default. Same as not setting the option. Profanity will pass from source to target.	彼はジャッカスです。	He is a jackass.
Marked	Profane words will be surrounded by XML tags and .	彼はジャッカスです。	He is a jackass.
Deleted	Profane words will be removed from the output without replacement.	彼はジャッカスです。	He is a.

Excluding content from translation

When translating content with tags such as HTML (contentType=text/html), it is sometimes useful to exclude specific content from translation. You may use the attribute class=notranslate to specify content that should remain in its original language. In the following example, the content inside the first div element will not be translated, while the content in the second div element will be translated.

HTML

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

GET /Translate

Implementation notes

Translates a text string from one language to another.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/Translate.
Return value: A string representing the translated text.
If you previously used AddTranslation or AddTranslationArray to enter a translation with a rating of 5 or higher for the same source sentence, Translate returns only the top choice that is available to your system. The "same source sentence" means the exact same (100% matching), except for capitalization, white space, tag values, and punctuation at the end of a sentence. If no rating is stored with a rating of 5 or above then the returned result will be the automatic translation by Microsoft Translator.

Response class (Status 200)

string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
text	(empty)	Required. A string representing the text to translate. The size of the text must not exceed 10000 characters.	query	string
from	(empty)	Optional. A string representing the language code of the translation text. For example, en for English.	query	string
to	(empty)	Required. A string representing the language code to translate the text into.	query	string
contentType	(empty)	Optional. The format of the text being translated. The supported formats are text/plain (default) and text/html. Any HTML needs to be a well-formed, complete element.	query	string
category	(empty)	Optional. A string containing the category (domain) of the translation. Defaults to "general".	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

POST /TranslateArray

Implementation notes

Use the TranslateArray method to retrieve translations for multiple source texts.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/TranslateArray.
The format of the request body should be as follows:

<TranslateArrayRequest>
  <AppId />
  <From>language-code</From>
  <Options>
    <Category xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2" >string-value</Category>
    <ContentType xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">text/plain</ContentType>
    <ReservedFlags xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2" />
    <State xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2" >int-value</State>
    <Uri xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2" >string-value</Uri>
    <User xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2" >string-value</User>
  </Options>
  <Texts>
    <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">string-value</string>
    <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">string-value</string>
  </Texts>
  <To>language-code</To>
</TranslateArrayRequest>

Elements within the TranslateArrayRequest are:

• appid: Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".
• from: Optional. A string representing the language code to translate the text from. If left empty the response will include the result of language auto-detection.
• options: Optional. An Options object which contains the values listed below. They are all optional and default to the most common settings. Specified elements must be listed in alphabetical order.
  • Category: A string containing the category (domain) of the translation. Defaults to general.
  • ContentType: The format of the text being translated. The supported formats are text/plain (default), text/xml and text/html. Any HTML needs to be a well-formed, complete element.
  • ProfanityAction: Specifies how profanities are handled as explained above. Accepted values of ProfanityAction are NoAction (default), Marked and Deleted.
  • State: User state to help correlate request and response. The same contents will be returned in the response.
  • Uri: Filter results by this URI. Default: all.
  • User: Filter results by this user. Default: all.
• texts: Required. An array containing the texts for translation. All strings must be of the same language. The total of all texts to be translated must not exceed 10000 characters. The maximum number of array elements is 2000.
• to: Required. A string representing the language code to translate the text into.

Optional elements can be omitted. Elements which are direct children of TranslateArrayRequest must be listed in alphabetical order.
TranslateArray method accepts application/xml or text/xml for Content-Type.
Return value: A TranslateArrayResponse array. Each TranslateArrayResponse has the following elements:

• Error: Indicates an error if one has occurred. Otherwise set to null.
• OriginalSentenceLengths: An array of integers indicating the length of each sentence in the original source text. The length of the array indicates the number of sentences.
• TranslatedText: The translated text.
• TranslatedSentenceLengths: An array of integers indicating the length of each sentence in the translated text. The length of the array indicates the number of sentences.
• State: User state to help correlate request and response. Returns the same content as in the request.

The format of the response body is as follows.

<ArrayOfTranslateArrayResponse xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <TranslateArrayResponse>
    <From>language-code</From>
    <OriginalTextSentenceLengths xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <a:int>int-value</a:int>
    </OriginalTextSentenceLengths>
    <State/>
    <TranslatedText>string-value</TranslatedText>
    <TranslatedTextSentenceLengths xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <a:int>int-value</a:int>
    </TranslatedTextSentenceLengths>
  </TranslateArrayResponse>
</ArrayOfTranslateArrayResponse>

Response class (Status 200)

A successful response includes an array of TranslateArrayResponse in format described above.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
Authorization	(empty))	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response. Common errors include: Array element cannot be empty Invalid category From language is invalid To language is invalid The request contains too many elements The From language is not supported The To language is not supported Translate Request has too much data HTML is not in a correct format Too many strings were passed in the Translate Request
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

POST /GetLanguageNames

Implementation notes

Retrieves friendly names for the languages passed in as the parameter languageCodes, and localized using the passed locale language.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/GetLanguageNames.
The request body includes a string array representing the ISO 639-1 language codes to retrieve the friendly names for. For example:

<ArrayOfstring xmlns:i="http://www.w3.org/2001/XMLSchema-instance"  xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <string>zh</string>
    <string>en</string>
</ArrayOfstring>

Return value: A string array containing languages names supported by the Translator Service, localized into the requested language.

Response class (Status 200)

A string array containing languages names supported by the Translator Service, localized into the requested language.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
locale	(empty)	Required. A string representing a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code to localize the language names or an ISO 639 lowercase culture code by itself.	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

GET /GetLanguagesForTranslate

Implementation notes

Obtain a list of language codes representing languages that are supported by the Translation Service. Translate and TranslateArray can translate between any two of these languages.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/GetLanguagesForTranslate.
Return value: A string array containing the language codes supported by the Translator Services.

Response class (Status 200)

A string array containing the language codes supported by the Translator Services.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

GET /GetLanguagesForSpeak

Implementation notes

Retrieves the languages available for speech synthesis.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/GetLanguagesForSpeak.
Return value: A string array containing the language codes supported for speech synthesis by the Translator Service.

Response class (Status 200)

A string array containing the language codes supported for speech synthesis by the Translator Service.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

GET /Speak

Implementation notes

Returns a wave or mp3 stream of the passed-in text being spoken in the desired language.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/Speak.
Return value: A wave or mp3 stream of the passed-in text being spoken in the desired language.

Response class (Status 200)

binary
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
text	(empty)	Required. A string containing a sentence or sentences of the specified language to be spoken for the wave stream. The size of the text to speak must not exceed 2000 characters.	query	string
language	(empty)	Required. A string representing the supported language code to speak the text in. The code must be present in the list of codes returned from the method GetLanguagesForSpeak.	query	string
format	(empty)	Optional. A string specifying the content-type ID. Currently, audio/wav and audio/mp3 are available. The default value is audio/wav.	query	string
options	(empty)	Optional. A string specifying properties of the synthesized speech: MaxQuality and MinSize are available to specify the quality of the audio signals. With MaxQuality, you can get voices with the highest quality, and with MinSize, you can get the voices with the smallest size. Default is MinSize. female and male are available to specify the desired gender of the voice. Default is female. Use the vertical bar `	to include multiple options. For exampleMaxQuality	Male`.
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

GET /Detect

Implementation notes

Use the Detect method to identify the language of a selected piece of text.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/Detect.
Return value: A string containing a two-character Language code for the given text. .

Response class (Status 200)

string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
text	(empty)	Required. A string containing some text whose language is to be identified. The size of the text must not exceed 10000 characters.	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

POST /DetectArray

Implementation notes

Use the DetectArray method to identify the language of an array of string at once. Performs independent detection of each individual array element and returns a result for each row of the array.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/DetectArray.
The format of the request body should be as follows.

<ArrayOfstring xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <string>string-value-1</string>
    <string>string-value-2</string>
</ArrayOfstring>

The size of the text must not exceed 10000 characters.
Return value: A string array containing a two-character Language codes for each row of the input array.
The format of the response body is as follows.

<ArrayOfstring xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <string>language-code-1</string>
  <string>language-code-2</string>
</ArrayOfstring>

Response class (Status 200)

DetectArray was successful. Returns a string array containing a two-character Language codes for each row of the input array.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

GET /AddTranslation

Implementation notes

Important
DEPRECATION NOTE: After January 31, 2018, this method will not accept new sentence submissions, and you will receive an error message. Please refer to this announcement about changes to the Collaborative Translation Functions.

Adds a translation to the translation memory.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/AddTranslation.

Response class (Status 200)

string
Response Content Type: application: xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
originalText	(empty)	Required. A string containing the text to translate from. The string has a maximum length of 1000 characters.	query	string
translatedText	(empty)	Required. A string containing translated text in the target language. The string has a maximum length of 2000 characters.	query	string
from	(empty)	Required. A string representing the language code of the translation text. en = english, de = german etc...	query	string
to	(empty)	Required. A string representing the language code to translate the text into.	query	string
rating	(empty)	Optional. An integer representing the quality rating for this string. Value between -10 and 10. Defaults to 1.	query	integer
contentType	(empty)	Optional. The format of the text being translated. The supported formats are "text/plain" and "text/html". Any HTML needs to be a well-formed, complete element.	query	string
category	(empty)	Optional. A string containing the category (domain) of the translation. Defaults to "general".	query	string
user	(empty)	Required. A string used to track the originator of the submission.	query	string
uri	(empty)	Optional. A string containing the content location of this translation.	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
410	AddTranslation is no longer supported.
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

POST /AddTranslationArray

Implementation notes

Important
DEPRECATION NOTE: After January 31, 2018, this method will not accept new sentence submissions, and you will receive an error message. Please refer to this announcement about changes to the Collaborative Translation Functions.

Adds an array of translations to add translation memory. This is an array version of AddTranslation.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/AddTranslationArray.
The format of the request body is as follows.

<AddtranslationsRequest>
  <AppId></AppId>
  <From>A string containing the language code of the source language</From>
  <Options>
    <Category xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">string-value</Category>
    <ContentType xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">text/plain</ContentType>
    <User xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">string-value</User>
    <Uri xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">string-value</Uri>
  </Options>
  <To>A string containing the language code of the target language</To>
  <Translations>
    <Translation xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">
      <OriginalText>string-value</OriginalText>
      <Rating>int-value</Rating>
      <Sequence>int-value</Sequence>
      <TranslatedText>string-value</TranslatedText>
    </Translation>
  </Translations>
</AddtranslationsRequest>

Elements within the AddtranslationsRequest element are:

• AppId: Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".
• From: Required. A string containing the language code of the source language. Must be one of the languages returned by the GetLanguagesForTranslate method.
• To: Required. A string containing the language code of the target language. Must be one of the languages returned by the GetLanguagesForTranslate method.
• Translations: Required. An array of translations to add to translation memory. Each translation must contain: originalText, translatedText and rating. The size of each originalText and translatedText is limited to 1000 chars. The total of all the originalText(s) and translatedText(s) must not exceed 10000 characters. The maximum number of array elements is 100.
• Options: Required. A set of options, including Category, ContentType, Uri, and User. User is required. Category, ContentType and Uri are optional. Specified elements must be listed in alphabetical order.

Response class (Status 200)

AddTranslationArray method was successful. After January 31, 2018, sentence submissions will not be accepted. The service will respond with error code 410.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
410	AddTranslation is no longer supported.
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

GET /BreakSentences

Implementation notes

Breaks a piece of text into sentences and returns an array containing the lengths in each sentence.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/BreakSentences.
Return value: An array of integers representing the lengths of the sentences. The length of the array is the number of sentences, and the values are the length of each sentence.

Response class (Status 200)

An array of integers representing the lengths of the sentences. The length of the array is the number of sentences, and the values are the length of each sentence.
integer
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
text	(empty)	Required. A string representing the text to split into sentences. The size of the text must not exceed 10000 characters.	query	string
language	(empty)	Required. A string representing the language code of input text.	query	string
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

POST /GetTranslations

Implementation notes

Retrieves an array of translations for a given language pair from the store and the MT engine. GetTranslations differs from Translate as it returns all available translations.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/GetTranslations.
The body of the request includes the optional TranslationOptions object, which has the following format.

<TranslateOptions xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">
  <Category>string-value</Category>
  <ContentType>text/plain</ContentType>
  <ReservedFlags></ReservedFlags>
  <State>int-value</State>
  <Uri>string-value</Uri>
  <User>string-value</User>
</TranslateOptions>

The TranslateOptions object contains the values listed below. They are all optional and default to the most common settings. Specified elements must be listed in alphabetical order.

• Category: A string containing the category (domain) of the translation. Defaults to "general".
• ContentType: The only supported, and the default, option is "text/plain".
• IncludeMultipleMTAlternatives: boolean flag to determine whether more than one alternatives should be returned from the MT engine. Valid values are true and false (case-sensitive). Default is false and includes only 1 alternative. Setting the flag to true allows for generating artificial alternatives in translation, fully integrated with the collaborative translations framework (CTF). The feature allows for returning alternatives for sentences that have no alternatives in CTF, by adding artificial alternatives from the n-best list of the decoder.
  • Ratings The ratings are applied as follows: 1) The best automatic translation has a rating of 5. 2) The alternatives from CTF reflect the authority of the reviewer, from -10 to +10. 3) The automatically generated (n-best) translation alternatives have a rating of 0, and have a match degree of 100.
  • Number of Alternatives The number of returned alternatives is up to maxTranslations, but may be less.
  • Language pairs This functionality is not available for translations between Simplified and Traditional Chinese, both directions. It is available for all other Microsoft Translator supported language pairs.
• State: User state to help correlate request and response. The same contents will be returned in the response.
• Uri: Filter results by this URI. If no value is set, the default is all.
• User: Filter results by this user. If no value is set, the default is all.

Request Content-Type should be text/xml.
Return value: The format of the response is as follows.

<GetTranslationsResponse xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <From>Two character language code</From>
  <State/>
  <Translations>
    <TranslationMatch>
      <Count>int-value</Count>
      <MatchDegree>int-value</MatchDegree>
      <MatchedOriginalText/>
      <Rating>int value</Rating>
      <TranslatedText>string-value</TranslatedText>
    </TranslationMatch>
  </Translations>
</GetTranslationsResponse>

This includes a GetTranslationsResponse element containing the following values:

• Translations: An array of matches found, stored in TranslationMatch (see below) objects. The translations may include slight variants of the original text (fuzzy matching). The translations will be sorted: 100% matches first, fuzzy matches below.
• From: If the method did not specify a From language, this will be the result of auto language detection. Otherwise it will be the given From language.
• State: User state to help correlate request and response. Contains the same value as given in the TranslateOptions parameter.

TranslationMatch object consists of the following:

• Error: If an error has occurred for a specific input string, the error code is stored. Otherwise the field is empty.
• MatchDegree: The system matches input sentences against the store, including inexact matches. MatchDegree indicates how closely the input text matches the original text found in the store. The value returned ranges from 0 to 100, where 0 is no similarity and 100 is an exact case sensitive match. MatchedOriginalText: Original text that was matched for this result. Only returned if the matched original text was different than the input text. Used to return the source text of a fuzzy match. Not returned for Microsoft Translator results.
• Rating: Indicates the authority of the person making the quality decision. Machine Translation results will have a rating of 5. Anonymously provided translations will generally have a rating of 1 to 4, whilst authoritatively provided translations will generally have a rating of 6 to 10.
• Count: The number of times this translation with this rating has been selected. The value will be 0 for the automatically translated response.
• TranslatedText: The translated text.

Response class (Status 200)

A GetTranslationsResponse object in the format described above.
string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
appid	(empty)	Required. If the Authorization or Ocp-Apim-Subscription-Key header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".	query	string
text	(empty)	Required. A string representing the text to translate. The size of the text must not exceed 10000 characters.	query	string
from	(empty)	Required. A string representing the language code of the translation text.	query	string
to	(empty)	Required. A string representing the language code to translate the text into.	query	string
maxTranslations	(empty)	Required. An integer representing the maximum number of translations to return.	query	integer
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	string	header
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.

POST /GetTranslationsArray

Implementation notes

Use the GetTranslationsArray method to retrieve multiple translation candidates for multiple source texts.
The request URI is https://api.microsofttranslator.com/V2/Http.svc/GetTranslationsArray.
The format of the request body is as follows.

<GetTranslationsArrayRequest>
  <AppId></AppId>
  <From>language-code</From>
  <MaxTranslations>int-value</MaxTranslations>
  <Options>
    <Category xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">string-value</Category>
    <ContentType xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">text/plain</ContentType>
    <ReservedFlags xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2"/>
    <State xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">int-value</State>
    <Uri xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">string-value</Uri>
    <User xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">string-value</User>
  </Options>
  <Texts>
    <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">string-value</string>
  </Texts>
  <To>language-code</To>
</GetTranslationsArrayRequest>

GetTranslationsArrayRequest includes the following elements:

• AppId: Required. If Authorization header is used, leave the appid field empty else include a string containing "Bearer" + " " + "access_token".
• From: Required. A string representing the language code of the translation text.
• MaxTranslations: Required. An integer representing the maximum number of translations to return.
• Options: Optional. An Options object which contains the values listed below. They are all optional and default to the most common settings. Specified elements must be listed in alphabetical order.
  • Category`: A string containing the category (domain) of the translation. Defaults to general.
  • ContentType: The only supported, and the default, option is text/plain.
  • IncludeMultipleMTAlternatives: boolean flag to determine whether more than one alternatives should be returned from the MT engine. Valid values are true and false (case-sensitive). Default is false and includes only 1 alternative. Setting the flag to true allows for generating artificial alternatives in translation, fully integrated with the collaborative translations framework (CTF). The feature allows for returning alternatives for sentences that have no alternatives in CTF, by adding artificial alternatives from the n-best list of the decoder.
    • Ratings The ratings are applied as follows: 1) The best automatic translation has a rating of 5. 2) The alternatives from CTF reflect the authority of the reviewer, from -10 to +10. 3) The automatically generated (n-best) translation alternatives have a rating of 0, and have a match degree of 100.
    • Number of Alternatives The number of returned alternatives is up to maxTranslations, but may be less.
    • Language pairs This functionality is not available for translations between Simplified and Traditional Chinese, both directions. It is available for all other Microsoft Translator supported language pairs.
• State: User state to help correlate request and response. The same contents will be returned in the response.
• Uri: Filter results by this URI. If no value is set, the default is all.
• User: Filter results by this user. If no value is set, the default is all.
• Texts: Required. An array containing the texts for translation. All strings must be of the same language. The total of all texts to be translated must not exceed 10000 characters. The maximum number of array elements is 10.
• To: Required. A string representing the language code to translate the text into.

Optional elements can be omitted. Elements which are direct children of GetTranslationsArrayRequest must be listed in alphabetical order.
Request Content-Type should be text/xml.
Return value: The format of the response is as follows.

<ArrayOfGetTranslationsResponse xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <GetTranslationsResponse>
    <From>language-code</From>
    <State/>
    <Translations>
      <TranslationMatch>
        <Count>int-value</Count>
        <MatchDegree>int-value</MatchDegree>
        <MatchedOriginalText>string-value</MatchedOriginalText>
        <Rating>int-value</Rating>
        <TranslatedText>string-value</TranslatedText>
      </TranslationMatch>
      <TranslationMatch>
        <Count>int-value</Count>
        <MatchDegree>int-value</MatchDegree>
        <MatchedOriginalText/>
        <Rating>int-value</Rating>
        <TranslatedText>string-value</TranslatedText>
      </TranslationMatch>
    </Translations>
  </GetTranslationsResponse>
</ArrayOfGetTranslationsResponse>

Each GetTranslationsResponse element contains the following values:

• Translations: An array of matches found, stored in TranslationMatch (see below) objects. The translations may include slight variants of the original text (fuzzy matching). The translations will be sorted: 100% matches first, fuzzy matches below.
• From: If the method did not specify a From language, this will be the result of auto language detection. Otherwise it will be the given From language.
• State: User state to help correlate request and response. Contains the same value as given in the TranslateOptions parameter.

TranslationMatch object consists of the following:

• Error: If an error has occurred for a specific input string, the error code is stored. Otherwise the field is empty.
• MatchDegree: The system matches input sentences against the store, including inexact matches. MatchDegree indicates how closely the input text matches the original text found in the store. The value returned ranges from 0 to 100, where 0 is no similarity and 100 is an exact case sensitive match.
• MatchedOriginalText: Original text that was matched for this result. Only returned if the matched original text was different than the input text. Used to return the source text of a fuzzy match. Not returned for Microsoft Translator results.
• Rating: Indicates the authority of the person making the quality decision. Machine Translation results will have a rating of 5. Anonymously provided translations will generally have a rating of 1 to 4, whilst authoritatively provided translations will generally have a rating of 6 to 10.
• Count: The number of times this translation with this rating has been selected. The value will be 0 for the automatically translated response.
• TranslatedText: The translated text.

Response class (Status 200)

string
Response Content Type: application/xml

Parameters

Parameter	Value	Description	Parameter Type	Data Type
Authorization	(empty)	Required if the appid field or Ocp-Apim-Subscription-Key header is not specified. Authorization token: "Bearer" + " " + "access_token".	header	string
Ocp-Apim-Subscription-Key	(empty)	Required if the appid field or Authorization header is not specified.	header	string

Response messages

HTTP Status Code	Reason
400	Bad request. Check input parameters and the detailed error response.
401	Invalid credentials
500	Server error. If the error persists, let us know. Please provide us with the approximate date & time of the request and with the request ID included in the response header X-MS-Trans-Info.
503	Service temporarily unavailable. Please retry and let us know if the error persists.