Informatielezen.nl

Microsoft have been offering an alternative to the Google Translator for a while now, and I’ve been using it commercially for one of our clients. It’s been free to use since forever, and it’s a good offering.

In the recent Microsoft BUILD conference, the Azure Marketplace was announced. It’s a centralized portal where you can purchase access to Microsoft’s offerings. This means that there is a system of tiered payment schemes for access to their applications. In the case of Microsoft Translator, you now have to purchase API access on a PER translation or PER transaction basis.

Nothing wrong with that, even Microsoft has to make their services sustainable. (It’s also a bit cheaper than the Google Translate API too, so that’s always a winner!) However, it’s not quite so straightforward!

I’ve been using the Microsoft Translator API freely for about a year now. Previously, you would generate your application ID, and simply connect to either their SOAP, HTTP or AJAX APIs with the app ID, and query away until your hearts content.

However, with the advent of the Azure Marketplace, Microsoft have done away with the appID and have introduced an OAuth authentication system. Now before you start worrying – don’t. If like me, you’ve had a nightmare with OAuth in the past, then you would be right to be dismayed. But Microsoft have delivered an authentication method that is very simple to query. We’re not actually having to consider much in terms of OAuth for ourselves – we’re just required to make an HTTP POST to a URL, and retrieve a token which we then use in our application.

In this article, I’m going to provide all of the code to get a complete translation working, along with a bit of discussion about why we’re doing certain things.
The authentication class
We need an OAuth token to authenticate ourselves with Microsoft, before using any of their services. When I originally read about this – I’ll be honest with you – I was concerned. I’ve heard horror stories about OAuth, and how it can cause more problems than it solves.
Luckily, that isn’t the case here, as it’s very easy to retrieve and use the authentication token. As such, the class that I’ve written is relatively simple, while having a number of features that will make your life easier. It’s also been designed to be used globally across the whole of the Azure Marketplace, so it’s largely reusable for other Microsoft services that use OAuth.AzureMarketplaceAuthenticator.class.php
I’m going to assume that you’ve already got your account set up correctly on the Azure Marketplace, and that you have a DataMarket account set up. In this, you will have a Client ID and a Client Secret, both of which are used to request the token.
The token has an expiry time, so we retrieve the it and store it for that period (minus ten seconds, for safety). When we then need to use it, we either use the stored version, or request a new one. This is handled by calling a single method (get_token):123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195 * @version $Id: $ */ /** * AzureMarketplaceAuthenticator * * Description: * * @author David Wilcock  */class AzureMarketplaceAuthenticator {    /**    * Directory of the token file    */   const TOKEN_DIRECTORY = ‘/tmp/’;    /**    * Grant type    */   const GRANT_TYPE = ‘client_credentials’;    /**    * OAuth query URL    */   const QUERY_URL = ‘https://datamarket.accesscontrol.windows.net/v2/OAuth2-13′;    /**    * The application scope    *    * @var String    */   private $str_application_scope;    /**    * Client ID from your application in Azure DataMarket    *    * @var String    */   private $str_client_id;    /**    * Client Secret from your application in Azure DataMarket    *    * @var String    */   private $str_client_secret;    /**    * The file where the token is stored    *    * @var String    */   private $str_token_file;    /**    * Both arguments are required for ANY operation, which is why they are in    * the constructor.    *    * @param String $str_client_id    * @param String $str_client_secret    */   public function __construct($str_client_id, $str_client_secret, $str_application_scope) {       $this->str_client_id = $str_client_id;      $this->str_client_secret = $str_client_secret;      $this->str_application_scope = $str_application_scope;       $this->str_token_file = self::TOKEN_DIRECTORY . sha1($this->str_client_id . $this->str_client_secret);    }    /**    * Retrieve the OAuth token to be used in Microsoft Datamarket Applications    *    * @return String    */   public function get_token(){       if ($this->token_has_expired()) {         $str_token = $this->request_new_token();      } else {         $str_token = $this->get_current_token_data();      }       return $str_token;    }    /**    * Has the token expired?    *    * @return Boolean    */   private function token_has_expired() {      if (file_exists($this->str_token_file)){         if ($this->get_current_expiry() <= time()){            return TRUE;         } else {            return FALSE;         }      } else {         return TRUE;      }   }    /**    * Gets a new token, stores and returns it    *    * @return String    */   private function request_new_token() {      $obj_connection = curl_init();      $arr_query_bits = array (         ’grant_type’ => self::GRANT_TYPE,         ’scope’ => $this->str_application_scope,         ’client_id’ => $this->str_client_id,         ’client_secret’ => $this->str_client_secret      );      $str_query = http_build_query($arr_query_bits);       curl_setopt($obj_connection, CURLOPT_URL, self::QUERY_URL);      curl_setopt($obj_connection, CURLOPT_HEADER, 0);      curl_setopt($obj_connection, CURLOPT_FOLLOWLOCATION, 1);      curl_setopt($obj_connection, CURLOPT_RETURNTRANSFER, 1);      curl_setopt($obj_connection, CURLOPT_POSTFIELDS, $str_query);      curl_setopt($obj_connection, CURLOPT_POST, TRUE);       $str_response = curl_exec($obj_connection);      $obj_response = json_decode($str_response);       if (is_null($obj_response)){         throw new Exception(“Response wasn’t VALID  - {$str_response}”);      }       if (isset($obj_response->error)){         throw new Exception($obj_response->error_description);      }       $this->store_token_response($obj_response);      return $obj_response->access_token;   }    /**    * Reads the token file.    * Forces a re-read using clearstatcache for thread safety    *    * @return String    */   private function read_token_file() {      $str_token = file_get_contents($this->str_token_file);      clearstatcache();      return $str_token;   }    /**    * Stores the token and expiry time as a json encoded string    *    * @param StdClass $obj_response    */   private function store_token_response($obj_response){      $arr_token_data = array(        ‘expires’ => time() + ($obj_response->expires_in – 10),        ‘data’ => $obj_response->access_token      );      file_put_contents($this->str_token_file, json_encode($arr_token_data));   }    /**    * Gets the token from the current file    *    * @return String    */   private function get_current_token_data(){      $arr_token = json_decode($this->read_token_file());      return $arr_token->data;   }    /**    * Gets the expiry time from the current file    *    * @return String    */   private function get_current_expiry(){      $arr_token = json_decode($this->read_token_file());      return $arr_token->expires;   } }The translation class

So now that we have a valid authentication token, we can use it to to query the Microsoft Translator API, and make a translation.
MicrosoftTranslator.class.php

In the constructor, we pass in the AzureMarketplaceAuthenticator object. We do this in the constructor, because we absolutely must have this authentication before we can do anything.

Take special note of how we’re using the token in the constructor – it’s passed in the HTTP header, and prefixed with the string “Authorization: Bearer “. This is a requirement of the OAuth 2.0 authorization specification.

Also note the workaround for the PHP bug, which in certain cases, can prevent the HTTP header being set correctly in a SOAP request.

The translate method accepts three parameters; source text, source language and target language. The source text is the text that you want translating. The source and target language, are two letter ISO 639-1 codes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

/**
* MicrosoftTranslator.class.php
*
* @author David Wilcock
* @version $Id: $
*/

class MicrosoftTranslator {

/**
* The WSDL URL
*/
const STR_WSDL_URL = ‘http://api.microsofttranslator.com/V2/Soap.svc’;

/**
* Constructor – requires an instance of AzureMarketplaceAuthenticator, prepares
* a SoapClient with the client credentials
*
* @param AzureMarketplaceAuthenticator $obj_auth
*/
public function __construct(AzureMarketplaceAuthenticator $obj_auth){
$str_auth_header = “Authorization: Bearer “. $obj_auth->get_token();
$arr_context = array(
‘http’ =>array(
‘header’ => $str_auth_header
)
);
/**
* This is here because of a bug:
* https://bugs.php.net/bug.php?id=49853
*/
ini_set(‘user_agent’, ‘PHP-SOAP/’ . PHP_VERSION . “\r\n” . $str_auth_header);
$obj_context = stream_context_create($arr_context);
$arr_options = array (
‘soap_version’ => ‘SOAP_1_2′,
‘encoding’ => ‘UTF-8′,
‘exceptions’ => true,
‘trace’ => true,
‘cache_wsdl’ => ‘WSDL_CACHE_NONE’,
‘stream_context’ => $obj_context
);
$this->obj_soap_connection = new SoapClient(self::STR_WSDL_URL, $arr_options);
}

/**
* Performs a translation request, returns the translated text
*
* @param string $str_source_text
* @param string $str_source_language
* @param string $str_target_language
* @return string
*/
public function translate($str_source_text = NULL, $str_source_language = NULL, $str_target_language = NULL) {
if (is_null($str_source_text) || is_null($str_source_language) || is_null($str_target_language)){
throw new Exception(“Invalid argument”);
}
$arr_request_arguments = array (
‘appId’ => ”, // no longer used, but pass it anyway
‘text’ => $str_source_text,
‘from’ => $str_source_language,
‘to’ => $str_target_language
);
$obj_soap_response = $this->obj_soap_connection->Translate($arr_request_arguments);
return $obj_soap_response->TranslateResult;
}

}

Executing some code!

So now that we have two classes, we need a script to trigger the translation. You’ll see how easy this is to implement, and incude in an existing project.
trigger.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

/**
* trigger.php
*
* @author David Wilcock
* @version $Id: $
*/

require_once ‘AzureMarketplaceAuthenticator.class.php’;
require_once ‘MicrosoftTranslator.class.php’;

try {

$obj_translator_auth = new AzureMarketplaceAuthenticator(‘azure_client_id’, ‘azure_client_secret’ ,’http://api.microsofttranslator.com’);
$obj_translator = new MicrosoftTranslator($obj_translator_auth);

echo $obj_translator->translate(‘This is a test for the Microsoft Translator API’, ‘en’, ‘de’) . PHP_EOL;

} catch (Exception $obj_exception) {
echo “Exception: ” . $obj_exception->getMessage() . PHP_EOL;
}

After running this, you should see something like this:

Dies ist ein Test für die Microsoft Translator API

Conclusion

It really is that simple!

You can build on this code very easily – I have myself written a large application around this, that uses queuing, retries, callbacks, etc. and if I do say so myself, it’s pretty slick.
Links

OAuth 2.0 authorization specification
PHP bug
ISO 639-1
Microsoft Translator at Microsoft Azure Marketplace

Files

I have attached a zip file containing all the files used in this article:

microsoft_translator_api.zip
More

If you have spotted a bug, or have a query, just reply to this post, and I’ll do my best to reply as soon as possible. Enjoy.