PHP SDK for Microsoft Translator

Table of content

1. Installation
2. Configuration
3. Usage
4. Change Log
5. Contribute

1. Installation

Requirements

The SDK needs the cURL PHP extension.

With composer

Install the latest stable version using composer: composer require potsky/microsoft-translator-php-sdk

Or add potsky/microsoft-translator-php-sdk to your composer.json :

{
    "require": {
        "potsky/microsoft-translator-php-sdk": "*"
    }
}

Manually

Is it time to move to composer?

Not now? Ok, just include src/MicrosoftTranslator.php in your PHP script :

include_once( 'src/MicrosoftTranslator.php' );

2. Configuration

2.1 Microsoft Account

1. Sign up for a Microsoft Azure account (credit card required)

   If you don’t already have an Azure account, sign up for a Microsoft Azure account at http://azure.com.

2. After you have created an Azure account, subscribe to Azure. You will not be charged for Azure unless you use it. Then sign into the Azure portal at http://portal.azure.com.

3. Add a Microsoft Translator API subscription to your Azure account.

   • Select the + New option
   • Select AI + Cognitive Services from the list of Azure services
   • Select either Translator Text API
   • Press the Create button when you’re ready to create your Microsoft Translator API subscription.
   • Complete the fields and press the Create button and you’re now subscribed to Microsoft Translator.

4. Retrieve your authentication key.

   • Go to All Resources and select the Microsoft Translator API subscription account you are subscribed to.
   • Select the Keys option and copy the first subscription key to access the service.

2.2 SDK

When instantiating a new client, you pass an array of configuration parameters:

$msTranslator = new MicrosoftTranslator\Client( $configuration );

Here is the list of available parameters, some are mandatory:

Name	Default	Description
api_client_key	mandatory	Your subscription key 1
api_access_token	-	You can directly give an access token. In this case api_client_key will not be used but this token longs only 10 minutes according to the microsoft documentation
api_base_url	http://api.microsofttranslator.com/V2/Http.svc/
auth_base_url	https://datamarket.accesscontrol.windows.net/v2/OAuth2-13/
guard_type	file	The only available type is file but you can specify your own Guard by setting the classname like this YourNameSpace\\YourGuardWhichImplementsTheMicrosoftTranslatorGuardInterface
guard_file_dir_path	The default PHP tmp directory	You can specify a custom directory. IT MUST NOT BE EXPOSED TO INTERNET given that clear access token will be stored in files...
log_level	No log	To enable log, choose the maximum severity you want to log in this list : \MicrosoftTranslator\Logger::LEVEL_DEBUG, \MicrosoftTranslator\Logger::LEVEL_INFO, \MicrosoftTranslator\Logger::LEVEL_WARNING, \MicrosoftTranslator\Logger::LEVEL_ERROR and \MicrosoftTranslator\Logger::LEVEL_FATAL
log_file_path	No file path, output with error_log() function	Set a file path to log in this file
http_timeout	10	The timeout in seconds for requests
http_proxy_host	-	The proxy host if you need a proxy for outgoing connections to the API
http_proxy_type	URLPROXY_HTTP	One of these values: URLPROXY_HTTP, CURLPROXY_SOCKS4, CURLPROXY_SOCKS5
http_proxy_auth	CURLAUTH_BASIC	One if these values: CURLAUTH_BASIC, CURLAUTH_NTLM
http_proxy_port	3128	The proxy port
http_proxy_user	-	The proxy user name if your proxy needs authentication
http_proxy_pass	-	The proxy user password if your proxy needs authentication
http_user_agent	MicrosoftTranslator PHP SDK v%VERSION%	You can use your own user agent and you can use the placeholder %VERSION% to inject the current SDK version

3. Usage

3.1 Methods

Define a client with your credentials:

<?php
include 'src/MicrosoftTranslator.php';

$msTranslator = new \MicrosoftTranslator\Client( array(
	'log_level'         => \MicrosoftTranslator\Logger::LEVEL_DEBUG ,
	'api_client_key'     => 'your-client-key' ,
) );

Translate a text

Translate word chair in german. The API will try to guess the input language:

print_r( $msTranslator->translate( 'chair' , 'de' )->getBody() );

Result:

Stuhl

Translate word chair in german by specifying the initial sentence is in french:

print_r( $msTranslator->translate( 'chair' , 'de' , 'fr' )->getBody() );

Result:

Fleisch

Translate an array of texts

print_r( $msTranslator->translateArray( array( 'dog' , 'cat' ) , 'fr' )->getBody() );

Result:

Array
(
    [dog] => chien
    [cat] => chat
)

You can specify an input language as usual.

Transform a text

Only english is supported.

print_r( $msTranslator->TransformText( 'WTF I am not here!' , 'en' )->getBody() );

Result:

Array
(
    [ec] => 0
    [em] => OK
    [sentence] => WHAT THE HECK I am not here!
)

Detect the language of a text

print_r( $msTranslator->detect( 'The dog is red' )->getBody() );

Result:

en

Detect the language of an array of texts

print_r( $msTranslator->detectArray( array( 'The dog is red' , 'Le chien est rouge' ) )->getBody() );

Result:

Array
(
    [The dog is red] => en
    [Le chien est rouge] => fr
)

Get language names

print_r( $msTranslator->getLanguageNames( 'fr' , array( 'en' , 'jp' , 'fr' ) )->getBody() );

Result:

Array
(
    [en] => Anglais
    [jp] =>
    [fr] => Français
)

Get available languages for translation

print_r( $msTranslator->getLanguagesForTranslate()->getBody() );

Result:

Array
(
    [0] => ar
    [1] => bs-Latn
    [2] => bg
    [3] => ca
    [4] => zh-CHS
    [5] => zh-CHT
    [6] => hr
    [7] => cs
    [8] => da
    [9] => nl
    ...
)

Break sentences

print_r( $msTranslator->breakSentences( 'The dog is red. The cat is blue. The fish is yellow submarine.' , 'en' )->getBody() );

Result:

Array
(
    [0] => The dog is red.
    [1] => The cat is blue.
    [2] => The fish is yellow submarine.
)

3.2 Handle errors

SDK can throw an MicrosoftTranslator\Exception in several cases :

• HTTP problems with cURL
• API problems...
• Wrong credentials
• ...

You should catch these errors like this:

try
{
	...

}
catch ( \MicrosoftTranslator\Exception $e )
{
	$error = sprintf( "Error #%s with message : %s" , $e->getCode() , $e->getMessage() );
	$msg   = sprintf( "|    %s    |" , $error );
	$line  = str_repeat( '-' , strlen( $msg ) );
	echo sprintf( "%s\n%s\n%s\n" , $line , $msg , $line );
}

or like this by checking the returned code instead:

try
{
	...
}
catch ( \MicrosoftTranslator\Exception $f )
{
	if ( $f->getCode() === 500 )
	{
		echo sprintf( "Oups, error #%s : %s." , $f->getCode() , $f->getMessage() );
	}
	else
	{
		echo sprintf( "Error #%s : %s\n" , $f->getCode() , $f->getMessage() );
	}
}

3.3 Customize the SDK

You can use your own classes to implement several parts of the SDK. Your classes need to implement interfaces and they will get the configuration array in the constructors. You can then customize your classes at runtime.

3.3.1 Inject a new Logger

You can use your own Logger class. The Logger class is used to log SDK messages.

It must implement the \MicrosoftTranslator\LoggerInterface interface.

Then use it when instantiating a client:

$msTranslator = new \MicrosoftTranslator\Client( $config , null , null , $my_logger );

3.3.2 Inject a new HTTP manager

You can use your own Http class. The Http class manages the HTTP connexions to reach the accumulator API.

It must implement the \MicrosoftTranslator\HttpInterface interface.

Then use it when instantiating a client:

$msTranslator = new \MicrosoftTranslator\Client( $config , $my_http_manager );

3.3.3 Inject a new Auth manager

You can use your own Auth class. The Auth class responsibility is to get an access token and to give it to the Guard manager.

It must implement the \MicrosoftTranslator\AuthInterface interface.

Then use it when instantiating a client:

$msTranslator = new \MicrosoftTranslator\Client( $config , null , $my_auth_manager );

3.3.4 Inject a new Guard manager

You can use your own Guard manager. The Guard class responsibility is to store access tokens and to manage expiration durations.

The Guard injection is a little bit different of others injections because it is done in the configuration array. This is a setter dependency injection instead of an instantiation dependency injection.

It must implement the \MicrosoftTranslator\GuardInterface interface.

Inject a new Guard manager via the configuration array:

$msTranslator = new \MicrosoftTranslator\Client( array(
	'guard_type' => 'MyNameSpace\\MyGuard'
) );

3.4 Manage saved access tokens

The SDK maintains access tokens via a Guard object. The default Guard is a GuardFile which stores access tokens in files.

If you need to delete all saved access token, you can do this:

$msTranslator->getAuth()->getGuard()->deleteAllAccessTokens();

To delete only expired access tokens, run this:

$msTranslator->getAuth()->getGuard()->cleanAccessTokens();

4. Change Log

• v0.0.3
  • Switch to Azure API
  • Add an example ready to use in the example directory
• v0.0.2
  • The SDK now returns a MicrosoftTranslator\Exception when access token cannot be retrieved
• v0.0.1
  • here is the beginning

5. Contribute

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Tests are in tests. To run the tests: vendor/bin/phpunit.

Coverage cannot decrease next a merge. To track file coverage, run vendor/bin/phpunit --coverage-html coverage and open coverage/index.html to check uncovered lines of code.