Azure Microsoft Translation in Windows Phone (The Easy Way)

There are few things more awesome than the Microsoft Translate service available on the Azure Marketplace. Unfortunately, the vast majority of examples of how to use it are not written for Windows Phone, which is missing some key components available in other .NET solutions.

(Note: Yes, I know you this should be easier with the Azure toolkit for Windows Phone, etc, etc, etc. I didn’t find the classes I needed in there and this blog post is for people like me who got stuck like me.)

So lets get started and we can see exactly how easily we can integrate this awesome translation service into a application.

Get this project on github

Step 1: Sign Up For Microsoft Translation in the Azure Marketplace

Let’s say we’ve never been to the Azure Marketplace. Let’s go there now and click on Sign-In.

We’ll go through a pretty typical registration process (name, rank and serial number) and then we’re signed in for an account. Now we need to sign up specifically for the Microsoft Translation service. Click on “Data”.

Do a search for “translation’” and Microsoft Translator will pop right up.

If we click on it, we’ll see some details as well as all of our pricing options.

Helpfully, at the bottom of that, there is an option for 2 million characters for the low, low price of free. This should be enough for us to get a fun little project started.

Now that we’re signed up for our free service, we need to register our specific app and get a Client ID and Client Secret to identify our app to this service. To do so, we will not click on “My Applications” or “My Data” or “Account Keys”, but down on the “Developers” link at the bottom.

Once you’re in there, Azure Marketplace will generate a client secret for you. All you need to do is give your application a client ID, some identifying name and a redirect URI. Don’t worry about the redirect URI, we won’t use it with this service.

Write down the ClientID and the Client Secret, we’ll need those for our app.

After we hit “Create”, we’ll see our application in the Registered Applications section.

And if we like we can click on “My Data” option in the “My Account” menu and try out our brand new service using a web interface.

We’re going to build our requests based on these queries, so go ahead and grab the “Service Root URL” at the top (should look like http://api.datamarket.azure.com/Data.ashx/Bing/MicrosoftTranslator/v1/ ). Play around with the query building and then we’ll work on our app.

Step 2: Get And Save Our Token

Let’s write our app already! Open Visual Studio and start a new “Windows Phone App” project.

First, so we don’t run into problems later, lets add some references. Right click on the references folder, “Add Reference…” and add System.Servicemodel.Web (which we’ll need to read JSON) and System.Xml.Linq (which we’ll need to read XML).

Add a “Services” folder and add two files, TranslationService.cs and TokenService.cs. Add a “Models” folder and add the file “AdmAccessToken.cs”.

The way this service works is to go out and get an access token for the client. This token will come back as our AdmAccessToken, which is valid for 10 minutes. We’ll use that token to authenticate our app with the service. We’re going to assume that we need a new token every time we open the app, but try to use the same token during each app session. (If you want to know more about the access tokens, head over here.)

The first 4 properties in AdmAccessToken.cs are required for proper serialization. The rest of the class is there for determining when the token has expired.

public class AdmAccessToken
{
    // required for deserialization
    public string access_token { get; set; }
    public string token_type { get; set; }
    public string expires_in { get; set; }
    public string scope { get; set; }

    // properties and methods for determining expired tokens
    private DateTime tokenEndTime { get; set; }

    public bool IsExpired()
    {
        DateTime now = DateTime.Now;
        double secondsLeft = tokenEndTime.Subtract(now).TotalSeconds;
        if(secondsLeft < 30)
            return true;
        else
            return false;
    }

    public void Initalize()
    {
        tokenEndTime = DateTime.Now.Add(new TimeSpan(0, 0, 600));
    }
}

Now we’ll write our token service in TokenService.cs. We’ll send an event once we get our token, so we need to define some event args for sending the token in the event. I usually add these to the bottom of my service class file.

public class TokenServiceCompleteEventArgs : EventArgs
{
    public TokenServiceCompleteEventArgs(bool isSuccess, AdmAccessToken token)
    {
        IsSuccess = isSuccess;
        TranslationToken = token;
    }

    public bool IsSuccess { get; private set; }
    public AdmAccessToken TranslationToken {get; private set;}
}

And add the event to the service class so we can raise it when we’re done.

public event EventHandler<TokenServiceCompleteEventArgs> AccessTokenComplete;
private void RaiseAccessTokenComplete(bool isSuccess, AdmAccessToken token)
{
    if(AccessTokenComplete!=null)
        AccessTokenComplete(this, new TokenServiceCompleteEventArgs(isSuccess, token));
}

We’re going to save our Client ID, Client Secret, and OAuth URL as string in the top of the class:

private static readonly string CLIENT_ID = "My_Translation_App";
private static readonly string CLIENT_SECRET = "[client secret from the registration process]";
private static readonly string OAUTH_URI = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13";

And then add our call for the token. Our process here is 1) check to see if we have a valid token. 2) If we have a valid token, return it. 3) If we don’t have a valid token, start our Http POST request to get a token.

public void GetToken()
{
    if (IsolatedStorageSettings.ApplicationSettings.Contains("admAccessToken"))
    {
        AdmAccessToken savedToken = (AdmAccessToken)IsolatedStorageSettings.ApplicationSettings["admAccessToken"];
        if (!savedToken.IsExpired())
        {
            RaiseAccessTokenComplete(true, savedToken);
            return;
        }
    }

    // Create our HTTP request
    WebRequest request = WebRequest.Create(OAUTH_URI);
    request.Method = "POST";
    request.ContentType = "application/x-www-form-urlencoded";

    //IAsyncResult postCallback = (IAsyncResult)request.BeginGetRequestStream(new AsyncCallback(RequestStreamReady), request);
    request.BeginGetRequestStream(new AsyncCallback(RequestStreamReady), request);
}

Then we write our POST data…

private void RequestStreamReady(IAsyncResult asyncResult)
{
    try
    {
        // Create the data we're going to write into the POST body
        string clientID = CLIENT_ID;
        string clientSecret = CLIENT_SECRET;
        string scope = "scope=" + HttpUtility.UrlEncode("http://api.microsofttranslator.com");
        string grant_type = "grant_type=" + HttpUtility.UrlEncode("client_credentials");
        String postBody = string.Format("{0}&client_id={1}&client_secret={2}&{3}", grant_type, HttpUtility.UrlEncode(clientID), HttpUtility.UrlEncode(clientSecret), scope);

        // Write the data to the POST body
        HttpWebRequest request = (HttpWebRequest)asyncResult.AsyncState;
        byte[] bytes = System.Text.Encoding.UTF8.GetBytes(postBody);
        Stream postStream = request.EndGetRequestStream(asyncResult);
        postStream.Write(bytes, 0, bytes.Length);
        postStream.Close();

        // Get the response (including the token)
        request.BeginGetResponse(new AsyncCallback(GetTokenResponseCallback), request);
    }
    catch (WebException webExc)
    {
        RaiseAccessTokenComplete(false, null);
    }
}

And get our response. We’ll save our token to IsolatedStorageSettings and then fire our event with the token attached.

private void GetTokenResponseCallback(IAsyncResult asyncResult)
{
    try
    {
        HttpWebRequest endRequest = (HttpWebRequest)asyncResult.AsyncState;
        HttpWebResponse response = (HttpWebResponse)endRequest.EndGetResponse(asyncResult);
        DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(AdmAccessToken));
        AdmAccessToken token = (AdmAccessToken)serializer.ReadObject(response.GetResponseStream());

        // Set the token so that it will begin the expiration process
        token.Initalize();
        // Let's set this token to be accessible on the app level
        App.SetTranslationToken(token);
        // And save the token to our app settings
        if (IsolatedStorageSettings.ApplicationSettings.Contains("admAccessToken"))
            IsolatedStorageSettings.ApplicationSettings["admAccessToken"] = token;
        else
            IsolatedStorageSettings.ApplicationSettings.Add("admAccessToken", token);
        IsolatedStorageSettings.ApplicationSettings.Save();
        // Finally, we're ready to send our token out into the wild
        RaiseAccessTokenComplete(true, token);
    }
    catch (WebException webExc)
    {
        RaiseAccessTokenComplete(false, null);
    }
}

We are now sufficiently token-ed and we’re ready to translate some things.

Step 3: Translate All The Things

Our real goal with the translation service is to enter some text, pick a source language, pick a target language and away we go.

To that end, we’ll set up some properties in TranslationService.cs to help us do this.

public class TranslationService
{
    private TokenService _tokenService;
    private string _originalText;
    private string _sourceLanguage;
    private string _targetLanguage;

    public TranslationService()
    {
        _tokenService = new TokenService();
        _tokenService.AccessTokenComplete += _tokenService_AccessTokenComplete;
    }
}

Then when we move to start the translation, we’ll run the token service, which will check to see if we have a valid token and, if we do, return it. (If we’ don’t, it will go and get one for us. When it is done with either task, it will raise the AccessTokenComplete event, which we’ll use to kick off the translation service.

public void GetTranslation(string originalText, string sourceLanguage, string targetLanguage)
{
    _originalText = originalText;
    _sourceLanguage = sourceLanguage;
    _targetLanguage = targetLanguage;

    _tokenService.GetToken();
}

void _tokenService_AccessTokenComplete(object sender, TokenServiceCompleteEventArgs e)
{
    if (e.IsSuccess)
        StartTranslationWithToken(e.TranslationToken);
    else
        RaiseTranslationFailed("There was a problem securing an access token");
}

The http service work is done in the StartTranslationWithToken method. We’ll set up the service uri we need to do the translation, create a WebRequest and set the Authorization header of our request to use “Bearer “ plus our access token. When the response comes back, we should have our XML with the data in it. We can read this using the XDocument utility (make sure to add System.XML.Linq to your project resources to get access to XDocument). Finally, we’ll raise an event that says everything went according to plan and returns our translation, as well as the original input data.

private void StartTranslationWithToken(AdmAccessToken token)
{
    string translateUri = string.Format("http://api.microsofttranslator.com/v2/Http.svc/Translate?text={0}&from={1}&to={2}",
        HttpUtility.UrlEncode(_originalText),
        HttpUtility.UrlEncode(_sourceLanguage),
        HttpUtility.UrlEncode(_targetLanguage));

    WebRequest translationRequest = HttpWebRequest.Create(translateUri);

    // We need to put our access token into the Authorization header 
    // with "Bearer " preceeding it.
    string bearerHeader = "Bearer " + token.access_token;
    translationRequest.Headers["Authorization"] = bearerHeader;

    // Finally call our translation service

    translationRequest.BeginGetResponse(asyncResult =>
    {
        try
        {
            HttpWebRequest request = (HttpWebRequest)asyncResult.AsyncState;

            HttpWebResponse response = (HttpWebResponse)request.EndGetResponse(asyncResult);

            // Read the contents of the response into a string
            Stream streamResponse = response.GetResponseStream();
            StreamReader streamRead = new StreamReader(streamResponse);
            string translationData = streamRead.ReadToEnd();

            // Read the XML return from the translator
            // you can get a preview of this XML if you go to your Azure
            // account, click on My Data on the left and then on "Use" on
            // Microsoft Translator. run a trial query and then click the 
            // XML button at the top of the query tool.

            // You'll need to add "System.XML.Linq" to your project to use XDocument
            XDocument translationXML = XDocument.Parse(translationData);
            string translationText = translationXML.Root.FirstNode.ToString();

            RaiseTranslationComplete(_originalText, _sourceLanguage, _targetLanguage, translationText);
        }
        catch (WebException webExc)
        {
            RaiseTranslationFailed(webExc.Status.ToString());
        }
    }, translationRequest);
}

In the interest of completeness, here is the class we made for the EventArgs that we use to return the translation (I added them to the bottom of my service cs file).

public class TranslationCompleteEventArgs : EventArgs
{
    public TranslationCompleteEventArgs(string originalText, string fromLang, string toLang, string translation)
    {
        OriginalText = originalText;
        FromLanguage = fromLang;
        ToLanguage = toLang;
        Translation = translation;
    }

    public string OriginalText { get; private set; }
    public string FromLanguage { get; private set; }
    public string ToLanguage { get; private set; }
    public string Translation { get; private set; }
}

public class TranslationFailedEventArgs :EventArgs
{
    public TranslationFailedEventArgs(string error)
    {
        ErrorDescription = error;
    }

    public string ErrorDescription { get; private set; }
}

And here are the events in my TranslationService class that we’ll fire after the translation is complete (or has failed).

public event EventHandler<TranslationCompleteEventArgs> TranslationComplete;
private void RaiseTranslationComplete(string originalText, string fromLang,
                                        string toLang, string translation)
{
    if (TranslationComplete != null)
        TranslationComplete(this, new TranslationCompleteEventArgs(originalText, fromLang, toLang, translation));
}

public event EventHandler<TranslationFailedEventArgs> TranslationFailed;
private void RaiseTranslationFailed(string error)
{
    if(TranslationFailed != null)
    TranslationFailed(this, new TranslationFailedEventArgs(error));
}

Now our translation is ready to rock and roll, so the only thing we have left to do is put together a simple user interface for interacting with our translator.

Step 3: Using Our Translator

Now lets build the UI that we’ll use to execute a translation and then (finally) translate something. Because this post is already running absurdly long We’re going to create UI for translating from English to Spanish rather than build up all the infrastructure for selecting multiple languages.

Open your project using Blend (you should be using Blend to create your Windows Phone UI) and go to the MainPage.xaml. Change the top text to the name of your app and the text beneath it to “translate”.

Beneath that, get rid of anything inside the ContentPanel and the hover your mouse along the left edge of the ContentPanel. you should see an orange line show up.

Click it and you’ll see that you’ve created a separation in your Grid layout. You’ll see numbers that indicate the status of the Grid.Row that you’ve made. Hover over those numbers and you’ll see an editing system pop up (note, this is for Blend 5 and up). Click in that pop-up to edit the size of the row.

I’m editing mine to be: 1*, 1*, which will look in the XAML like

<Grid.RowDefinitions>
    <RowDefinition Height="1*"/>
    <RowDefinition Height="1*"/>
</Grid.RowDefinitions>

The top area will be for the source text (what we want to translate), the middle area will be for selection of the translation languages (which we won’t implement in this tutorial) and the bottom will be where we’ll place the translated text.

To this end, let’s add a TextBlock indicating the function of the top and bottom areas and a TextBox for adding or copying text. I’m going to add some text into our source TextBox just to give us something to work with.

Let’s also give our TextBoxes names so we can add and extract text from them in the code-behind. By clicking on the element in the Objects and Timeline tree, we can see the properties on the right hand side.

Just change the name at the top to make it accessible by that name in the code-behind.

We’ll start the translation using an app bar button. Instead of explaining all of the application bar creation, I’ll point you to this post that goes through it on Blend.

When the user clicks on the ApplicationBar button, we’ll fire an event that starts up the translation service. To define this event, select your ApplicationBarIconButton in the Objects and Timeline panel.

‘
Then click the lightning icon in Properties panel. This will bring up a list of events that are available to that object. In the “Click” box, type the name of the event handler you’d like to use and Blend will insert the appropriate code into the code behind.

Now, to look at our code behind (MainPage.xaml.cs). Before we call the translation service, we need to initiate it. So at the top of our class, we’ll add our translation service, instantiate it and add some event handlers in our constructor.

TranslationService _translator;

public MainPage()
{
    InitializeComponent();
    _translator = new TranslationService();
    _translator.TranslationComplete += _translator_TranslationComplete;
    _translator.TranslationFailed += _translator_TranslationFailed;
}

Let’s start our translation service in our ApplicationBarIconButton event handler. We’ll hard code the language information for now from English to Spanish, but if you need a list of supported language codes, check out this… um… list of supported language codes.

private void On_CheckClicked(object sender, System.EventArgs e)
{
    _translator.GetTranslation(sourceTextBox.Text, "en", "es");
}

And all we need to do is handle the resulting events and we’re done. The TranslationService will return the information off the UI thread, so in order to pass the information along without throwing a thread exception, Deployment.Current.Dispatcher.BeginInvoke to the rescue!

void _translator_TranslationComplete(object sender, TranslationCompleteEventArgs e)
{
    Deployment.Current.Dispatcher.BeginInvoke(() =>
    {
        targetTextBox.Text = e.Translation;
    });
}

void _translator_TranslationFailed(object sender, TranslationFailedEventArgs e)
{
    Deployment.Current.Dispatcher.BeginInvoke(() =>
    {
        MessageBox.Show("Bummer, the translation failed. \n " + e.ErrorDescription);
    });
}

And we’re done! Don’t forget, you can grab the entire project on github. So check it out.

Thanks to Laurence Moroney of netNavi.tv for his post on this topic that helped me fill in some key missing pieces.