Getting Started with Microsoft Translator

[This is preliminary documentation and is subject to change.]

Even as the world becomes smaller through the use of many modern communication methods, language differences still create a chasm between people. How can this barrier be overcome when creating software or websites? The answer lies in machine translation. This paper will help users get started using the Microsoft Translator API in software that they write using any of four methods: a Web widget, AJAX, HTTP, or SOAP.

The Translator Web Widget – Translating an Entire Site

Easily use the Microsoft Translator Web Widget for basic website translation scenarios. Simply copy and paste a code snippet anywhere and customize the resulting translator box with different colors and sizes.

Visitors to a site can then modify the widget with specific views and automatic translation to their purposes, using a tool bar, and there is the additional feature of reverse translation - once a page has been translated, simply hover the mouse over the translated material to view the original language again.

To begin using the web widget, go to https://go.microsoft.com/?linkid=9656123. Follow the directions on the page by specifying a site address and the site’s original language. Select a width and color, and agree to the Microsoft terms of use, then click the Generate code button.

Once the code is generated, copy it to your clipboard and paste it into the html of your site where you would like the translation box to appear. Adding the Microsoft Translator to a web page is simple and quick. You can use it to enhance your site by making it a truly world-wide web site.

Using the AJAX API – Translating a Block of Text

Using AJAX minimizes bandwidth consumption and server response time. The AJAX interface of the Microsoft Translator allows development of more advanced web scenarios and can deliver instant translation of specified web content quickly and efficiently. It contains much of the same functionality as the Web Widget but is capable of additional customization. The magic is that the translation service can be called from the client-side code asynchronously so it does not require a full page refresh.

Imagine a scenario where a page on a site requires acceptance of a disclaimer before visitors can proceed to other areas of the site. It might be nice to make the disclaimer understandable to people who speak different languages so that they feel comfortable accepting the nuances of the disclaimer. A developer could offer a translation service by placing small clickable flags representing different languages at the bottom of the disclaimer box. The Microsoft Translator AJAX API presents an easy way to do this to swiftly deliver the results to the user.

To begin, you must obtain an appId for your project to access the Translator. Generate the appId by going to https://www.microsofttranslator.com/Dev/Ajax.

Paste the generated script within the header section of the code for your web project. Next, create a button to click for the translation, in this case a Spanish flag (spanish_flag.gif).

<asp:ImageButton  ID="btnSpanish" runat="server"  ImageUrl="~/Images/spanish_flag.gif"  onclientclick="translateDocument(); return false;" />

The disclaimer can now be translated using the below code by setting the desired languages (in this case from English to Spanish).

function translateDocument()
{
       // Tell  the API to translate from English into Spanish
       Microsoft.Translator.translate(document.body,  "en", "es");
}

If no language value is set for the current page, the translator will automatically detect the present language used on the page using language identification technology. The language can also be specified using the HTML lang attribute (e.g. lang=”en”). Using this attribute on either the HTML element or on specific page elements overrides the language of the page. This is the recommended method for pages containing text from multiple languages.

Instead of using hard coded language codes it is also possible can use variables to set the language on button-click. For example, to add a German flag (german_flag.gif) which can be clicked to translate the page to German, add the following code which identifies German as the desired language.

<asp:ImageButton ID="btnGerman"  runat="server" Height="20px" Width="30px"  ImageUrl="~/Images/german_flag.gif" onclientclick="translateDisclaimer(german);return  false;" />

This will call the following code when the flag is clicked. The translateDisclaimer method is called which uses the method mentioned above to translate the page to the desired language.

function translateDisclaimer(language)
{
Microsoft.Translator.translate(document.body,  currentLanguage, language);
currentLanguage = language;
}

For this method to work, the language variables must be set. The following code provides examples for Spanish, German, and English.

// Set the languages
        var  currentLanguage = "en";
        var  spanish = "es";
        var  german = "de";
        var  english = "en";

Using the HTTP API – Detecting the Language of a Block of Text

The HTTP interface allows development of web application scenarios and exposes HTTP GET & POST methods. The interface is technology agnostic; no particular operating system or programming languages are needed to develop with it. The HTTP API uses the same protocols and verbs as the world wide web and is simpler than AJAX, but requires a full page refresh when a request is made.

This HTTP example reveals how the Microsoft Translator can be used to detect and identify the language on a page using ASP.NET. On a web page add a textbox, button, and output label. The created page can look something like this:

Next, add a click event handler for the button.

protected void btnTranslate_Click(object sender,  EventArgs e)  }
{

Next, go to the Microsoft Translator HTTP Interface page at https://search.live.com/developers/appids.aspx to retrieve a valid appId. Sign in with your Windows Live ID and generate an application ID according to the instructions.

Add the URL with the appropriate appId to the code (replace the highlighted code below with your application ID). In the following code example, the txtInput.Text value indicates what the user will be typing into the text box on your web page.

WebRequest req =  System.Net.WebRequest.Create(@"https://api.microsofttranslator.com/V1/Http.svc/Detect?appId=yourappIdhere&text="  + txtInput.Text);

The code snippet below makes a request to the Microsoft Translator to read the data and put it into a string. It then sends back the language code.

WebResponse resp = req.GetResponse();
Stream strm = resp.GetResponseStream();
StreamReader reader = new  System.IO.StreamReader(strm);
string locale = reader.ReadToEnd();

Now create an output label where the detected language is identified to end users. In this case, locale is the variable that gets filled in by the response data.

lblOutput.Text = "The detected language is:  " + locale;

When a user enters text to be recognized by the page, the results look as follows:

The resulting language detected by the program (the “locale”) is identified as “en” for English as that is what the HTTP method returns. The next section will instruct on how to make this message more user friendly.

This example showed how to call the HTTP method. Since this is an http GET request, it can be used across a wide range of development languages.

Using the SOAP API – Connecting the Language List

SOAP is a great API for the Microsoft Translator since it is capable of returning simplified information to a third party, therefore enabling the following example. The SOAP interface supports client application scenarios and a rich .NET service client programming model. Developers can use their development technology of choice with this interface.

In the case of the HTTP Demo above, the detected language was identified as “en” - not the most intuitive result. Not everyone knows that “en” is for English, and even less people might know that “es” stands for Spanish or “de” stands for German. Learn how to make the result more recognizable in the next example using ASP.NET.

In Visual Studio 2008, to add a reference to a SOAP web service, right-click on the solution and add a service reference to https://api.microsofttranslator.com/V1/Soap.svc. This will generate the proxy code in a LanguageServiceClient class in the project.

For the SOAP interface, you must obtain another Live Search API App ID. Go to https://search.live.com/developers/appids.aspx, sign in with your Windows Live ID, and follow the instructions to generate the appId for the SOAP method.

Use the generated text in place of the highlighted yourappIdhere in the following code snippets.

Next, add a static dictionary using the following code. The dictionary and corresponding strings handle the conversion of the language code into the actual language name.

private static Dictionary<string, string>  languages = new Dictionary<string, string>();

In order to call the SOAP web service in the C# code, an instance of the LanguageServiceClient class is required. This instance is created using a static constructor. Then two string arrays are needed to populate the dictionary, one for the language code and the other for the language name. Remember to use the appropriate appId in place of yourappIdhere below (obtain your appId from https://search.live.com/developers/appids.aspx).

{
TranslatorService.LanguageServiceClient client = new  TranslatorService.LanguageServiceClient();
        string[] locales = client.GetLanguages("yourappIdhere");
        string[] names = client.GetLanguageNames("yourappIdhere",  "en");
       for  (int i = 0; i < locales.Length; i++)
       {
              languages[locales[i]] = names[i];
       }
}

The output label text can now be set so that it displays the full language name.

lblOutput.Text = "The detected  language is: '" + locale + "' which is the language code for "  + languages[locale] + ".";

When a user enters text to be recognized by a page, the following should appear:

This example showed how to call the SOAP methods. Although easy for .NET developers, there are drawbacks if it is called from the server as it requires a post back to the server to call the method. In contrast, with the AJAX interface, the method is called from the client side (directly from the browser) which is quicker and uses less bandwidth.

Summary

Microsoft’s Translator API can be easily implemented using the Web Widget, AJAX, HTTP, and SOAP interfaces. It is possible for the SOAP and HTTP methods to be invoked from a rich client (WPF or Win Forms) application, for example a plug-in for Live Messenger.

Translators have fast become essential resources for today’s social networking activities and online consumer marketplace. Make use of the unique and exciting opportunity to develop with the Microsoft Translator, and help implement effortless communication worldwide.