Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

GetTranslationsArray Method

Use the GetTranslationsArray method to retrieve multiple translation candidates for multiple source texts.

Method Request URI
POST http://api.microsofttranslator.com/V2/Http.svc/GetTranslationsArray

Parameter Description


Required. If the Authorization header is used, leave the appid field empty else a string containing "Bearer" + " " + access token.


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.


Required. A string representing the language code of the translation text.


Required. A string representing the language code to translate the text into.


Required. An int representing the maximum number of translations to return.


Optional. A TranslateOptions object which contains the values listed below. They all default to the most common settings. You do not need to set any of the values.

  • Category : A string containing the category (domain) of the translation. Defaults to "general".
  • ContentType : The only supported, and the default, option is "text/plain".
  • 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.
  • State : User state to help correlate request and response. The same contents will be returned in the response.

Request Headers

The following table describes required and optional request headers.

Request Header Description


Required. Specify the the value of access_token in format "Bearer" + " " + Access Token Value

Request Body

The format of the request body is as follows

    <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>
    <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">string-value</string>


Returns a GetTranslationsResponse array. Each GetTranslationsResponse has the following elements:

Name Description
GetTranslationsResponse A GetTranslationsResponse 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 A 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 Body

The format of the response body 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">

Ff512418.alert_note(en-us,MSDN.10).gif Note

Bing App ID is deprecated and is no longer supported.   Please obtain an access token to use the Microsoft Translator API. For details, go here.



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Runtime.Serialization.Json;
using System.Runtime.Serialization;
using System.Web;
using System.ServiceModel.Channels;
using System.ServiceModel;
using System.Xml;
using System.Xml.Linq;

namespace MicrosoftTranslatorSdk.HttpSamples
    class Program
        static void Main(string[] args)
            AdmAccessToken admToken;
            string headerValue;
            //Get Client Id and Client Secret from https://datamarket.azure.com/developer/applications/
            //Refer obtaining AccessToken (http://msdn.microsoft.com/en-us/library/hh454950.aspx) 
            AdmAuthentication admAuth = new AdmAuthentication("clientID", "client secret");
                admToken = admAuth.GetAccessToken();
                // Create a header with the access_token property of the returned token
                headerValue = "Bearer " + admToken.access_token;
            catch (WebException e)
                Console.WriteLine("Press any key to continue...");
            catch (Exception ex)

                Console.WriteLine("Press any key to continue...");
        private static void GetTranslationsArrayMethod(string authToken)
            string uri = "http://api.microsofttranslator.com/v2/Http.svc/GetTranslationsArray";
            string requestBody = String.Format("<GetTranslationsArrayRequest>" +
           "  <AppId>{0}</AppId>" +
           "  <From>{1}</From>" +
           "  <Options>" +
           "  <Category xmlns=\"http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2\">general</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\"/>" +
           "  <Uri xmlns=\"http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2\">{2}</Uri>" +
           "  <User xmlns=\"http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2\">{3}</User>" +
           "  </Options>" +
           "  <Texts>{6}</Texts>" +
           "  <To>{4}</To>" +
           "  <MaxTranslations>{5}</MaxTranslations>" +
           "</GetTranslationsArrayRequest>", "", "es", "", "TestUserId", "en", "3", "{0}");
            string translationsCollection = String.Empty;
            string[] textTranslations = { "a veces los errores son divertidos", " una importante contribución a la rentabilidad de la empresa" };
            // build the Translations collection
            translationsCollection += String.Format("<string xmlns=\"http://schemas.microsoft.com/2003/10/Serialization/Arrays\">{0}</string>", textTranslations[0]);
            translationsCollection += String.Format("<string xmlns=\"http://schemas.microsoft.com/2003/10/Serialization/Arrays\">{0}</string>", textTranslations[1]);
            // update the body
            requestBody = string.Format(requestBody, translationsCollection);

            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
            request.ContentType = "text/xml";
            request.Headers.Add("Authorization", authToken);
            request.Method = "POST";
            using (System.IO.Stream stream = request.GetRequestStream())
                byte[] arrBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(requestBody);
                stream.Write(arrBytes, 0, arrBytes.Length);
            WebResponse response = null;
                response = request.GetResponse();
                using (Stream respStream = response.GetResponseStream())
                    StreamReader rdr = new StreamReader(respStream, System.Text.Encoding.ASCII);
                    string strResponse = rdr.ReadToEnd();
                    XDocument doc = XDocument.Parse(@strResponse);
                    XNamespace ns = "http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2";
                    int i = 0;
                    foreach (XElement xe in doc.Descendants(ns + "GetTranslationsResponse"))
                        Console.WriteLine("\n\nSource Text: '{0}' Results", textTranslations[i++]);
                        int j = 1;
                        foreach (XElement xe2 in xe.Descendants(ns + "TranslationMatch"))
                            Console.WriteLine("\nCustom translation :{0} ", j++);
                            foreach (var node in xe2.Elements())
                                Console.WriteLine("{0} = {1}", node.Name.LocalName, node.Value);
                Console.WriteLine("Press any key to continue...");
                if (response != null)
                    response = null;
        private static void ProcessWebException(WebException e)
            Console.WriteLine("{0}", e.ToString());
            // Obtain detailed error information
            string strResponse = string.Empty;
            using (HttpWebResponse response = (HttpWebResponse)e.Response)
                using (Stream responseStream = response.GetResponseStream())
                    using (StreamReader sr = new StreamReader(responseStream, System.Text.Encoding.ASCII))
                        strResponse = sr.ReadToEnd();
            Console.WriteLine("Http status code={0}, error message={1}", e.Status, strResponse);


Goto Top


class AccessTokenAuthentication {
     * Get the access token.
     * @param string $grantType    Grant type.
     * @param string $scopeUrl     Application Scopr URL.
     * @param string $clientID     Application client ID.
     * @param string $clientSecret Application client ID.
     * @param string $authUrl      Oauth Url.
     * @return string.
    function getTokens($grantType, $scopeUrl, $clientID, $clientSecret, $authUrl){
        try {
            //Initialize the Curl Session.
            $ch = curl_init();
            //Create the request Array.
            $paramArr = array (
                 'grant_type'    => $grantType,
                 'scope'         => $scopeUrl,
                 'client_id'     => $clientID,
                 'client_secret' => $clientSecret
            //Create an Http Query.//
            $paramArr = http_build_query($paramArr);
            //Set the Curl URL.
            curl_setopt($ch, CURLOPT_URL, $authUrl);
            //Set HTTP POST Request.
            curl_setopt($ch, CURLOPT_POST, TRUE);
            //Set data to POST in HTTP "POST" Operation.
            curl_setopt($ch, CURLOPT_POSTFIELDS, $paramArr);
            //CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
            curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
            //CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
            curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
            //Execute the  cURL session.
            $strResponse = curl_exec($ch);
            //Get the Error Code returned by Curl.
            $curlErrno = curl_errno($ch);
                $curlError = curl_error($ch);
                throw new Exception($curlError);
            //Close the Curl Session.
            //Decode the returned JSON string.
            $objResponse = json_decode($strResponse);
            if ($objResponse->error){
                throw new Exception($objResponse->error_description);
            return $objResponse->access_token;
        } catch (Exception $e) {
            echo "Exception-".$e->getMessage();

 * Class:HTTPTranslator
 * Processing the translator request.
Class HTTPTranslator {
     * Create and execute the HTTP CURL request.
     * @param string $url        HTTP Url.
     * @param string $authHeader Authorization Header string.
     * @param string $postData   Data to post.
     * @return string.
    function curlRequest($url, $authHeader, $postData=''){
        //Initialize the Curl Session.
        $ch = curl_init();
        //Set the Curl url.
        curl_setopt ($ch, CURLOPT_URL, $url);
        //Set the HTTP HEADER Fields.
        curl_setopt ($ch, CURLOPT_HTTPHEADER, array($authHeader,"Content-Type: text/xml"));
        //CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
        curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
        //CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
        curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, False);
        if($postData) {
            //Set HTTP POST Request.
            curl_setopt($ch, CURLOPT_POST, TRUE);
            //Set data to POST in HTTP "POST" Operation.
            curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
        //Execute the  cURL session.
        $curlResponse = curl_exec($ch);
        //Get the Error Code returned by Curl.
        $curlErrno = curl_errno($ch);
        if ($curlErrno) {
            $curlError = curl_error($ch);
            throw new Exception($curlError);
        //Close a cURL session.
        return $curlResponse;

     * Create Request XML Format.
     * @param string $fromLanguage   Source language Code.
     * @param string $toLanguage     Target language Code.
     * @param string $category       Category.
     * @param string $contentType    Content Type.
     * @param string $user           User Type.
     * @param string $inputStrArr    Input String Array.
     * @param string $maxTranslation MaxTranslation Count.
     * @return string.
    function createReqXML($fromLanguage,$toLanguage,$category,$contentType,$user,$inputStrArr,$maxTranslation) {
        //Create the XML string for passing the values.
        $requestXml = '<GetTranslationsArrayRequest>';
        $requestXml .= '<AppId></AppId>';
        $requestXml .= '<From>'.$fromLanguage.'</From>';
        $requestXml .= '<Options>'.
                  '<Category xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">'.$category.'</Category>'.  
                 '<ContentType xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">'.$contentType.'</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"/>'.  
                 '<Uri xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2"></Uri>'. 
                 '<User xmlns="http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2">'.$user.'</User>'. 
        $requestXml .= '<Texts>';
        foreach($inputStrArr as $str) {
            $requestXml .= '<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">'.$str.'</string>';
        $requestXml .= '</Texts>';
        $requestXml .= '<To>'.$toLanguage.'</To>';
        $requestXml .= '<MaxTranslations>'.$maxTranslation.'</MaxTranslations>';
        $requestXml .= '</GetTranslationsArrayRequest>';
        return $requestXml;

try {
    //Client ID of the application.
    $clientID       = "clientid";
    //Client Secret key of the application.
    $clientSecret = "clientsecret";
    //OAuth Url.
    $authUrl      = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13/";
    //Application Scope Url
    $scopeUrl     = "http://api.microsofttranslator.com";
    //Application grant type
    $grantType    = "client_credentials";

    //Create the AccessTokenAuthentication object.
    $authObj      = new AccessTokenAuthentication();
    //Get the Access token.
    $accessToken  = $authObj->getTokens($grantType, $scopeUrl, $clientID, $clientSecret, $authUrl);
    //Create the authorization Header string.
    $authHeader = "Authorization: Bearer ". $accessToken;

    //Set the Params.
    $fromLanguage   = "de";
    $toLanguage        = "en";
    $user            = 'Testuser';
    $category       = "general";
    $uri             = null;
    $contentType    = "text/plain";
    $maxTranslation = 5;

    //Input text Array.
    $inputStrArr = array("Wir versuchen, offensiven Wortschatz bzw.", "Techniker arbeiten, um das Problem zu beheben");

    //HTTP GetTranslationsArray Method Url.
    $getTranslationUrl = "http://api.microsofttranslator.com/V2/Http.svc/GetTranslationsArray";

    //Create the Translator Object.
    $translatorObj = new HTTPTranslator();

    //Get the Request XML Format.
    $requestXml = $translatorObj->createReqXML($fromLanguage,$toLanguage,$category,$contentType,$user,$inputStrArr,$maxTranslation);

    //Call HTTP Curl Request.
    $curlResponse = $translatorObj->curlRequest($getTranslationUrl, $authHeader, $requestXml);

    // Interprets a string of XML into an object.
    $xmlObj = simplexml_load_string($curlResponse);
    $translationResponse = $xmlObj->GetTranslationsResponse;
    foreach($translationResponse as $translationArr) {
        $translationMatchArr = $translationArr->Translations->TranslationMatch;
        echo "Get Translation For <b>$inputStrArr[$i]</b>";
        echo "<table border ='2px'>";
        echo "<tr><td><b>Count</b></td><td><b>MatchDegree</b></td>
        foreach($translationMatchArr as $translationMatch) {
            echo "<tr><td>$translationMatch->Count</td><td>$translationMatch->MatchDegree</td><td>$translationMatch->Rating</td>
        echo "</table></br>";
} catch (Exception $e) {
    echo "Exception: " . $e->getMessage() . PHP_EOL;
Goto Top
© 2015 Microsoft