GetTranslations Method
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.
| Method | Request URI |
|---|---|
| POST | http://api.microsofttranslator.com/V2/Http.svc/GetTranslations |
| Parameter | Description |
|---|---|
|
appId |
Required. If the Authorization header is used, leave the appid field empty else a string containing "Bearer" + " " + access token. |
|
text |
Required. A string representing the text to translate. The size of the text must not exceed 10000 characters. |
|
from |
Required. A string representing the language code of the translation text. |
|
to |
Required. A string representing the language code to translate the text into. |
|
maxTranslations |
Required. An int representing the maximum number of translations to return. |
|
options |
Optional.
A TranslateOptions object which contains the values listed below. They are all optional and default to the most common settings.
|
The following table describes required and optional request headers.
| Request Header | Description |
|---|---|
|
Authorization |
Required. Specify the the value of access_token in format "Bearer" + " " + Access Token Value |
The format of the TranslateOptions request parameter is as follows
<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>
| Name | Description |
|---|---|
| GetTranslationsResponse |
A GetTranslationsResponse containing the following values:
|
| TranslationMatch |
A TranslationMatch object consists of the following:
|
The format of the response body 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>
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. |
Example
C#PHP
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");
try
{
admToken = admAuth.GetAccessToken();
// Create a header with the access_token property of the returned token
headerValue = "Bearer " + admToken.access_token;
GetTranslationsMethod(headerValue);
}
catch (WebException e)
{
ProcessWebException(e);
Console.WriteLine("Press any key to continue...");
Console.ReadKey(true);
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
Console.WriteLine("Press any key to continue...");
Console.ReadKey(true);
}
}
private static void GetTranslationsMethod(string authToken)
{
string text = "una importante contribución a la rentabilidad de la empresa";
string uri = "http://api.microsofttranslator.com/v2/Http.svc/GetTranslations?text=" + text + "&from=" + "es" + "&to=" + "en" + "&maxTranslations=5";
string requestBody = GenerateTranslateOptionsRequestBody("general", "text/plain", "", "", "", "TestUserId");
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
request.Headers.Add("Authorization", authToken);
request.ContentType = "text/xml";
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;
try
{
response = request.GetResponse();
using (Stream respStream = response.GetResponseStream())
{
StreamReader rdr = new StreamReader(respStream, System.Text.Encoding.ASCII);
string strResponse = rdr.ReadToEnd();
Console.WriteLine(string.Format("Available translations for source text '{0}' are", text));
XDocument doc = XDocument.Parse(@strResponse);
XNamespace ns = "http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2";
int i = 1;
foreach (XElement xe in doc.Descendants(ns + "TranslationMatch"))
{
Console.WriteLine("{0}Result {1}", Environment.NewLine, i++);
foreach (var node in xe.Elements())
{
Console.WriteLine("{0} = {1}", node.Name.LocalName, node.Value);
}
}
}
Console.WriteLine("Press any key to continue...");
Console.ReadKey(true);
}
catch
{
throw;
}
finally
{
if (response != null)
{
response.Close();
response = null;
}
}
}
// builds the outter xml body
private static string GenerateTranslateOptionsRequestBody(string category, string contentType, string ReservedFlags, string State, string Uri, string user)
{
string body = "<TranslateOptions xmlns=\"http://schemas.datacontract.org/2004/07/Microsoft.MT.Web.Service.V2\">" +
" <Category>{0}</Category>" +
" <ContentType>{1}</ContentType>" +
" <ReservedFlags>{2}</ReservedFlags>" +
" <State>{3}</State>" +
" <Uri>{4}</Uri>" +
" <User>{5}</User>" +
"</TranslateOptions>";
return string.Format(body, category, contentType, ReservedFlags, State, Uri, user);
}
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
<?php
class AccessTokenAuthentication {
/*
* Get the access token.
*
* @param string $grantType Grant type.
* @param string $scopeUrl Application Scope 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);
if($curlErrno){
$curlError = curl_error($ch);
throw new Exception($curlError);
}
//Close the Curl Session.
curl_close($ch);
//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.
*
* @return string.
*
*/
function curlRequest($url, $authHeader) {
//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", 'Content-Length: 0'));
//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);
//Set HTTP POST Request.
curl_setopt($ch, CURLOPT_POST, TRUE);
//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.
curl_close($ch);
return $curlResponse;
}
}
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.
$inputStr = "una importante contribución a la rentabilidad de la empresa";
$fromLanguage = "es";
$toLanguage = "en";
$user = 'TestUser';
$category = "general";
$uri = null;
$contentType = "text/plain";
$maxTranslation = 5;
//Create the string for passing the values through GET method.
$params = "from=$fromLanguage".
"&to=$toLanguage".
"&maxTranslations=$maxTranslation".
"&text=".urlencode($inputStr).
"&user=$user".
"&uri=$uri".
"&contentType=$contentType";
//HTTP getTranslationsMethod URL.
$getTranslationUrl = "http://api.microsofttranslator.com/V2/Http.svc/GetTranslations?$params";
//Create the Translator Object.
$translatorObj = new HTTPTranslator();
//Call the curlRequest.
$curlResponse = $translatorObj->curlRequest($getTranslationUrl, $authHeader);
//Interprets a string of XML into an object.
$xmlObj = simplexml_load_string($curlResponse);
$translationObj = $xmlObj->Translations;
$translationMatchArr = $translationObj->TranslationMatch;
echo "Get Translation For <b>$inputStr</b>";
echo "<table border ='2px'>";
echo "<tr><td><b>Count</b></td><td><b>MatchDegree</b></td>
<td><b>Rating</b></td><td><b>TranslatedText</b></td></tr>";
foreach($translationMatchArr as $translationMatch) {
echo "<tr><td>$translationMatch->Count</td><td>$translationMatch->MatchDegree</td><td>$translationMatch->Rating</td>
<td>$translationMatch->TranslatedText</td></tr>";
}
echo "</table></br>";
} catch (Exception $e) {
echo "Exception: " . $e->getMessage() . PHP_EOL;
}
Note