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

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 http://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";

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 http://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(@"http://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.

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

{
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];
       }
}

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

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.