Using the free Bing Translation APIs

Among the many cool free APIs that you can get from Bing is one that offers Machine Translation of any of your content. In addition to the translation widget that we covered in another article, which automatically scans your page and translates content that it finds, you get a finer control over what is translated. So, say for example, you want to keep your site in English, but someone sends feedback or makes a comment in another language, and you want that language to be translated, then the API can be used.

In this article you’ll see how to do that. You’ll get a free Bing AppID, which is needed to access the API, and then you’ll build a simple site that uses the API to translate content sent to you by your users.

Getting a Bing AppID

1. If you don’t already have one, you’ll need a Windows Live ID. You can get one by visiting https://signup.live.com/signup.aspx and signing up.

2. To get your Bing App ID, visit http://www.bing.com/developers/appids.aspx, and sign in with your Windows Live ID.

3. Click the “Get started by applying for an AppId now” link

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

5. Your new AppId will be generated and will appear with the Application Name and AppId. It’ll be a long hexadecimal string. You can disable, enable, and delete IDs that appear here.

6. Bing will store these ID’s for you, so it’s a good idea to bookmark the page, so that you’ll know where to go back to get them.

Using the Translator API on your site.

Create a site easily with WebMatrix

Let’s now create a simple web site. You’ll use Microsoft WebMatrix, a free tool that makes it easy to create, customize and publish sites. You can download it from http://www.microsoft.com/web/webmatrix. After installing it, come back here, and the screens you see will make a little more sense.

1. Create a new website in WebMatrix by clicking Site from Template

2. In the templates list, you’ll see an ‘Empty Site’ template. Use this to create new site and name it Windows-Live-Translator

3. Press OK, and WebMatrix will create the site for you. You’ll see a number of workspaces, denoted by the tabs across the left hand side. Select the ‘Files’ workspace.

4. You’ll see that the workspace is empty. Create a new CSHTML file by pressing the ‘New’ button in the toolbar

5. This will give you a dialog where you can choose lots of different file types. Select CSHTML, and name it Web-Translator.cshtml

6. Within the <body> tag in the CSHTML, add the following code:

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

7. Press the Run button, and you should see something like this within your browser. Remember that the code above should be between the <body> and </body> tags or it won’t work:

8. If you try clicking the button, nothing happens! That is because we haven’t added the code to do the translation yet.

What you’ve just created is an HTML form. It’s a standard way of doing data entry within web pages. You’ve probably seen hundreds like it. When you use a form, you do something called a POST to the server, where you send data up to the server. The server can then get this data and do something with it.

In our case we’re going to POST the text up to the server, along with the language that we want to translate the text into. The server will take the data, translate it, and then send back the translated text in the form of new HTML content to go within our page.

Microsoft Translator provides a service in the cloud that can we will call to get the translated text. Thus the flow is

1. User presses Translate Button

2. Page POSTS the data to your server

3. Server sends the data to the Bing Translator cloud service

4. Server gets a response from the cloud service

5. Server updates HTML and sends it back to the browser.

In the next section you’ll see how to do this.

Using the Translator Cloud Service

The service is hosted at http://api.microsofttranslator.com/v2/Http.svc. In this section you’ll learn some of the simple classes the WebMatrix gives you for communicating with the cloud to get data such as translated text back. This service takes four parameters. The first is your appID, this validates that you are who you say you are. The second is the text you want to translate, and the third and fourth are the codes for the languages that you are translating from and to respectively.

The first thing we’re going to do is to add the code to your CSHTML page that allows the user to POST the data to the server so that the server can handle it. You’re going to use the really simple ‘Razor’ programming syntax for this. Razor is just simple inline C# code, using the .NET Framework.

If you look back at the HTML you wrote earlier, you’ll see that on the <form> tag, the action was left empty. That means that this page will capture the post itself. When the browser navigates to the page, it generates a GET request to the server, and the server processes this by giving the HTML defined by the page back to the browser. That’s what happens whenever you browse a site. In this case, when you POST, you are posting back to the same page, and the server will execute code that is only executed in a post session, which in this case is the translation.

Add the following code to the top of the Web-Translator.cshtml file, above the <!DOCTYPE html> tag.

@{

string appId = "<your Bing appId>";

string fromLang = "en";

string translatedText = "";

if (IsPost) {

}

}

The @ character indicates that this is going to be Razor code, which will execute on the server whenever the page is called, be it by the browser with a GET, or by the user pressing on the button, causing a POST.

You’ll see that one section reads ‘if (IsPost)’ – which means that all code within that block will only be executed on a POST, so, we want our translation to happen when the user presses the button, so lets do it within the if(IsPost) block.

Add the call to the Microsoft Translator cloud service to the If(IsPost) block.

if (IsPost) {

string tobetranslated = Request["tobeTranslated"];

string toLang = 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=" + fromLang + "&to=" + toLang;

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();

}

· The text that was entered into the form was entered into a textArea called ‘tobeTranslated’. As such, the text is passed up to the server and retrieved using Request[“tobeTranslated”]. Similarly the language choice is available from Request[“languageChoice”]

· If no text was entered, we simply return HTML telling them to enter text.

If the text box was not blank, we then create the URI that is the service call with the 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).

The HttpWebRequest class in .NET can be used to create a request to a service, and provides the response from that service as a ‘WebResponse’ class. This response is a stream which can then be read by a StreamReader.

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

More information about Windows Live Translator and its widget can be found at http://sdk.microsofttranslator.com and http://www.microsofttranslator.com/mix2010/.

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!