Using the Windows Live Translator API

While it’s not yet a substitute for a full localization of your site, Machine Translation can be very useful in giving users who don’t speak your language a better experience when visiting you. The Microsoft Translator API allows you to add this in-site, instead of them having to visit a third party translation service. In this article, you’ll see how simple it is to add it, and how you can be up and running in just a few minutes.

You’ll first see how to create a simple web site and then add the API. If you have a site already, you can skip the first section!

Microsoft WebMatrix is a free tool that allows you to create, customize and publish websites. It’s amazingly easy to use, and can be downloaded from www.microsoft.com/web/webmatrix. We’ll be using this tool as we go along this tutorial.

Create a new web site using a WebMatrix template

WebMatrix gives you a number of different ways that you can create a new web site. You can use an existing open source application such as WordPress, Joomla, DotNetNuke or Umbraco, or you can create a site yourself by either coding everything or by using a small, simple template. You can see the options in the WebMatrix welcome screen.

A great place to start is the Empty Site template for this example. This is a full-featured HTML5 site. Select ‘Templates’ on the WebMatrix welcome screen.

image

Select the ‘Empty Site’, give the site the name ‘Translator API’, and press OK.

image

Select the Files workspace. You’ll see the button to do this on the lower left hand side of the screen.

image

Create a new .cshtml file by clicking on the new tab in the menu ribbon and give it a name.

image

A simple, empty HTML5 valid document is created.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title></title>
    </head>
    <body>
    </body>
</html>

Get a valid Bing API AppID

Before you can use the AJAX, HTTP or SOAP interfaces of the Translator API you must obtain a valid Bing API AppID. The Widget will only require an AppID if you wish to use the collaborative translations functionality. In this section you’ll see how to do that, step by step.

Visit the Bing AppId page at www.bing.com/developers/appids.aspx.

Sign in with your Windows Live ID or sign up for a Windows Live ID if you do not already have one. Click the “Add” button.

image

Complete the “create a new AppId” form, accept the terms of agreement, and submit the form by clicking “agree”

image

Your new AppId will be generated and will appear with the Application Name and AppId. You can disable, enable, and delete IDs that appear here.

image

Copy the AppID before you close the browser! You can return to this page whenever you need to retrieve any of your Bing AppIds.

Add the Translator HTTP API to the empty site

Let’s go back to WebMatrix. Right now, we simply have a blank HTML page that is waiting for us to add our code.

One way to use the Translator HTTP API is to send requests and retrieve the response from the web server. We will request and retrieve the server’s response by using a post form. In the body of our document, add a simple form.

<h1>Using Windows Live Translator's HTTP API</h1>
<form method="post" action="">
    <div>
        <label for="tobeTranslated">Type the text you want translated:</label>
        <br />
        <textarea name="tobeTranslated" rows="5" cols="20" id="inputText"></textarea>
    </div>
    I want to translate to:
    <select name="languageChoice">
        <option value="es" >Spanish</option>
        <option value="fr">French</option>
        <option value="it">Italian</option>
    </select>
    <input type="submit" value="Translate Now!" />
</form> 

This simple form will allow users to type in the text they want translated, to choose the language they want translated and submit their input to the server.

If you run the file in your browser, it should look like this:

image

If you try clicking the button, nothing happens! That is because we haven’t told the server to post back the information we have entered into the form.

To use the HTTP API for the Microsoft Translator service, we need to send an xml request to the appropriate http://api.microsofttranslator.com/V2/HTTP.svc URI and then parse the returned response. This code can be written at the top of our document.

@{
    string appId = "B7EEA5C1113D5C123BC0859402A76B920EAA0B38";
    string originallanguage = "en";
    string translatedText = "";
    
    if (IsPost) {
        string tobetranslated = Request["tobeTranslated"];   
        string languagechoice = Request["languageChoice"];
        
        if (tobetranslated == "") {
           <text>
            <p style="color:red;">Please enter text to be translated!</p>
            </text>
        } else {
        
        string uri = "http://api.microsofttranslator.com/v2/Http.svc/Translate?appId=" + appId + "&text=" + tobetranslated + "&from=" + originallanguage + "&to=" + languagechoice;

        HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);     
        WebResponse response = request.GetResponse();
        Stream strm = response.GetResponseStream();
        StreamReader reader = new System.IO.StreamReader(strm);
        translatedText = reader.ReadToEnd();
        Response.Write("The translated text is: '" + translatedText + "'.");
        response.Close();
        }
    }
}

We first request the values that the user entered into the form: the text they wanted translated and the language to which they want to translate the text.

Next we check if the user did not submit any text. If the user does not submit text and simply clicked the translate button, they receive a message in red prompting them to type in text to translate.

If the text box was not blank, we then create the URI that will be sent to the translator and store it in a string. The translate method requires 4 parameters to be sent: a string of our Bing appId (@appId), the text that we want to translate (@tobetranslated), the original language of the text (@from), and the language in which we want to translate the text (@to).

We do a web request and response to retrieve a text string translated from the original language to the language chosen by the user. A simple Response.Write outputs the translated message to the top of the page.

Run the file and input some text.

More information about Windows Live Translator and it’s widget can be found at sdk.microsofttranslator.com and www.microsofttranslator.com.

You can discuss this article using the adjacent Facebook talkback.

For technical questions please visit our discussion forums, where we have a vibrant community of developers like you, as well as Microsoft engineers who are ready to answer your questions!