UPDATE
Google has deprecated its Translation service, hence it will not be available for download anymore.

Google translation is an interesting service. Not only can you do language translation, you can also detect the language of a particular text. I recently needed to create a WordPress plugin to translate post titles from one language to another. As the translation API is only available for Java and Javascript, I decided to create a quick one for PHP. In this post we will see how to translate text from one language to another in a simple and quick way using the created class.

Getting the class

Before we begin you need to get the PHP class from below.

Testing the class

The Translation class used cURL to access the Google translation service, so you need to have that installed. A quick way to check if the class is working correctly is to use the ‘selfTest’ method of the class.

<?php
 
require_once('googleTranslate.class.php');
 
$gt = new GoogleTranslateWrapper();
$gt->selfTest();
 
?>

Which will print ‘Test Ok’ if everything is working fine.

Translating text

Once you are sure that the class is working properly, you can use the following simple example to translate a piece of text from one language to another.

<?php
 
require_once('googleTranslate.class.php');
 
/* Initialize the class translate class */
$gt = new GoogleTranslateWrapper();
$sampleText = "Bonjour de cette partie du monde";
 
/* translate(string, to_language, from_language) */
echo $gt->translate($sampleText , "en", "fr");
 
/* This should print 'Hello from this part of the world' */
 
?>

The first parameter of the ‘translate()’ method takes the text to translate, the second and third parameters take the target language to translate to and the language to translate from, respectively. You can eliminate the third parameter, the language name to translate from, and Google will automatically detect the source language and translate the text. This can be useful if you are not sure of the source language but want to translate and also detect the same. A short example is given below. The following will convert the sample text and also detect the source language (French here).

<?php
 
require_once('googleTranslate.class.php');
 
$gt = new GoogleTranslateWrapper();
$test = "Bonjour de cette partie du monde";
/* Convert from English */
$gt->translate($test, "en");
echo $gt->getDetectedSource();
 
?>

Errors during translation

If the class fails to translate the text for some reason, you can read the error message using the ‘getLastError’ method.

.
.
echo $gt->getLastError();
.

The class also provides the ‘isSuccess’ method to check if the translation was successful.

/* Was translation successful */
if(!$gt->isSuccess()) {
    echo $gt->getLastError();
}

Detecting language of a text block

You can also detect the language of a particular text block as shown below. This can be quite useful if you would like to detect the language of a web page or a block of a chat conversation.

<?php
 
require_once('googleTranslate.class.php');
$gt = new GoogleTranslateWrapper();
 
/* Detect the language of the given text */
$text = "For me, it is far better to grasp
        the Universe as it really is than
        to persist in delusion, however
        satisfying and reassuring.";
 
print_r($gt->detectLanguage($text));
 
?>

This will output an array with the following response elements:

[language] => en
[isReliable] => 1
[confidence] => 0.7626736

The first index gives the language code for the given text block. The second index represents a boolean value showing whether or not the detected language code is reliable for the given text. The third and last parameter is a numeric value between 0 – 1.0 that represents the confidence level in the language detected for the given text.

Caching

The class also has the facility to cache the results, so if you post a text for translation and it is already in the cache the cached results will be returned instead of going out to Google for translation, this helps decrease translation time. The cache can be enabled or disabled as below, by default the cache is enabled.

<?php
require_once('googleTranslate.class.php');
 
$gt = new GoogleTranslateWrapper();
/* Enable the cache */
$gt->cacheEnabled(true);
 
/* This will disable the cache; by default the cache is enabled */
$gt->cacheEnabled(false);
?>

Make sure that the ‘cache’ directory is there in the directory where your php file is located. If you need to locate the ‘cache’ directory somewhere different than you can change it in the ‘googleTranslate.class.php’ file. Locate the following line in the file, and then change the directory path to the one you want.

private $_cache_directory = './cache/';

Setting correct Referer header

Google requires that you send the referrer header with every request. Although it works without it, it is recommended that you use it. You can add a referrer header as below:

.
.
$gt = new GoogleTranslateWrapper();
$gt->setReferrer("http://www.your_site_name.com");
.
.

This sends your site name in the ‘Referer’ header in the request.

Passing valid credentials

Although the class works without you providing a apiKey – using a key in your application/site is completely optional, Google recommends adding your API key and a IP address during the translation request. This helps Google detect valid requests coming from your site and helps it in contacting you in case a need arises. You can signup for the api key here.

You can pass a API key and a IP address using the following.

<?php
 
require_once('googleTranslate.class.php');
 
$apiKey = "YOUR API KEY";
/* Change to your IP address */
$ip = "127.0.0.1";
 
$gt = new GoogleTranslateWrapper();
 
$gt->setCredentials($apiKey, $ip);
$test = "mon nom est Sameer";
echo $gt->translate($test, "en");
 
?>

Passing correct content headers

Make sure you have the following code at the start of your php code:

<?php
 
header("Content-type: text/html; charset=utf-8");
.
.

or if the page is html, the following in your head tags:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

Not setting the correct content type will display gibberish characters for Chinese and texts that have special characters.

Language Codes

Below is a list of language codes you can use during translation.

"af"-Afrikaans
"sq"-Albanian
"ar"-Arabic
"hy"-Armenian ALPHA
"az"-Azerbaijani ALPHA
"eu"-Basque ALPHA
"be"-Belarusian
"bg"-Bulgarian
"ca"-Catalan
"zh-CN"-Chinese
"hr"-Croatian
"cs"-Czech
"da"-Danish
"nl"-Dutch
"en"-English
"et"-Estonian
"tl"-Filipino
"fi"-Finnish
"fr"-French
"gl"-Galician
"ka"-Georgian ALPHA
"de"-German
"el"-Greek
"ht"-Haitian Creole ALPHA
"iw"-Hebrew
"hi"-Hindi
"hu"-Hungarian
"is"-Icelandic
"id"-Indonesian
"ga"-Irish
"it"-Italian
"ja"-Japanese
"ko"-Korean
"lv"-Latvian
"lt"-Lithuanian
"mk"-Macedonian
"ms"-Malay
"mt"-Maltese
"no"-Norwegian
"fa"-Persian
"pl"-Polish
"pt"-Portuguese
"ro"-Romanian
"ru"-Russian
"sr"-Serbian
"sk"-Slovak
"sl"-Slovenian
"es"-Spanish
"sw"-Swahili
"sv"-Swedish
"th"-Thai
"tr"-Turkish
"uk"-Ukrainian
"ur"-Urdu ALPHA
"vi"-Vietnamese
"cy"-Welsh
"yi"-Yiddish

Installing the GAPI class

The following code uses the GAPI – Google Analytics API PHP Interface to help us access the Analytics data. So before proceeding you need to download the class file from the GAPI home.

Dimensions & Metrics

Before we start a small primer on Google Analytics Dimensions & Metrics will be helpful.

What is a dimension?
Dimensions are things like browser and country, browser versions, landing and exit pages, the URL of a page, and the source website a visitor has come from.
Google Analytics uses the following 5 main marketing dimensions for analysis:

* Source
* Medium
* Term
* Content
* Campaign

What is a metric?
Metrics are the quantitative measure of a dimension for specific data types, such as counts of new visitors, page views, unique page views etc.

Getting the Google Analytics data

Now that we have seen what Dimensions & Metrics are we will proceed with an example. In this example we will fetch the ‘source’ dimension, which shows the source website the visitor is coming from and the ‘visits’ metric. This tells us how many visitors are coming from a particular source to our site.

<?php
 
require 'gapi-1.3/gapi.class.php';
 
/* Set your Google Analytics credentials */
define('ga_account'     ,'YOUR ANALYTICS EMAIL');
define('ga_password'    ,'YOUR ANALYTICS PASSWORD');
define('ga_profile_id'  ,'ANALYTICS SITE PROFILE ID');
 
$ga = new gapi(ga_account,ga_password);
 
/* We are using the 'source' dimension and the 'visits' metrics */
$dimensions = array('source');
$metrics    = array('visits');
 
/* We will sort the result be desending order of visits, 
    and hence the '-' sign before the 'visits' string */
$ga->requestReportData(ga_profile_id, $dimensions, $metrics,'-visits');
 
$gaResults = $ga->getResults();
 
$i=1;
 
foreach($gaResults as $result)
{
    printf("%-4d %-40s %5d\n",
           $i++,
           $result->getSource(),
           $result->getVisits());
}
 
echo "\n-----------------------------------------\n";
echo "Total Results : {$ga->getTotalResults()}";    
 
?>

Below I’ve listed the top ten results of the output.

No.  Source                                   Visits
------------------------------------------------------
1    google                                   10549
2    (direct)                                  1484
3    stumbleupon.com                           1338
4    webintenta.com                             159
5    bing                                       142
6    yahoo                                      115
7    feedburner                                  97
8    phpdeveloper.org                            70
9    t3n.de                                      64
10   clearspace.openqa.org                       43

As you can see the main method in the class is the ‘requestReportData()’, which has the following structure:

function requestReportData($report_id,      
                           $dimensions, 
                           $metrics, 
                           $sort_metric=null, 
                           $filter=null, 
                           $start_date=null, 
                           $end_date=null, 
                           $start_index=1, 
                           $max_results=30)

You can get the Dimension and Metric result by prefixing ‘get’ to the dimension or metric name. For e.g, if you metric name is ‘region’, you can get the result by using:

$result->getRegion();

Although I have only provided a single Dimension and Metric in the example code, the $dimensions and $metrics parameter can take multiple parameters as shown below:

$dimensions = array('source', 'region');
$metrics    = array('visits');

Bear in mind to specify a valid ‘dimension-metric’ combination as given in the API Docs. Specifying an invalid combination will return 0 results.

The output after adding the ‘region’ dimension is shown below.

No. Source     Region               Visits
-----------------------------------------
1   google     (not set)              965
2   google     England                796
3   google     California             650
4   google     Maharashtra            343
5   google     Karnataka              340
6   google     Tamil Nadu             295
7   google     New York               225
8   google     Andhra Pradesh         189
9   google     Texas                  172
10  google     Ontario                165

Modifying the amount of results returned

By default the class returns the first 30 results, although the raw Google API returns 1000 results by default. You can increase the same by changing the $max_results parameter. Google Analytics returns a maximum of 10,000 results, even if you set the $max_results parameter above 10,000. To get the results above that limit you need to set the $start_index parameter to 10,000, which will then get the results starting at 10,000.

$ga->requestReportData(ga_profile_id,
                       $dimensions,
                       $metrics,
                       '-visits', // Sort by 'visits' in descending order
                       '','','', // We are not using this paras yet
                       1,  // Start Index
                       500 // Max results
                       );

You can get the total number of results by using the getTotalResults() method. This can be helpful in pagination.

$ga->getTotalResults();

Setting the Google Analytics report period

By default the class returns the data for the last 1 month from today if no report period is specified. You can specify the report period as below. The date format is in the form ‘YYYY-MM-DD’.

$ga->requestReportData(ga_profile_id,
                       $dimensions,
                       $metrics,
                       '-visits', // Sort by 'visits' in descending order
                       '',
                       '2009-10-01', // Start Date
                       '2009-12-31', // End Date
                       1,  // Start Index
                       500 // Max results
                       );

Filtering the data

You can further filter the results using the $filter parameter. Filtering is a little tricky, so be sure to read the Google documentation.

$filter = 'country == United States';
 
$ga->requestReportData(ga_profile_id,
                       $dimensions,
                       $metrics,
                       '-visits', // Sort by 'visits' in descending order
                       $filter, // Filter the data
                       '2009-10-01', // Start Date
                       '2009-12-31', // End Date
                       1,  // Start Index
                       500 // Max results
                       );

You can also combine various options:

$filter = 'country == United States && visitorType == New Visitor';
// OR
$filter = 'country == United States &&
           visitorType == New Visitor &&
           browser == Firefox';

Getting a list of your Google Analytics Accounts

Most users have more than one profiles in their Analytics account. You can easily get a list of all your accounts (sitename – profileid) with the following code.

<?php
 
require 'gapi-1.3/gapi.class.php';
 
/* Set your Google Analytics credentials */
define('ga_account'     ,'YOUR ANALYTICS EMAIL');
define('ga_password'    ,'YOUR ANALYTICS PASSWORD');
 
$ga = new gapi(ga_account,ga_password);
 
$gaResult = $ga->requestAccountData();
 
foreach($gaResult as $result)
{
  printf("%-30s %15d\n", $result, $result->getProfileId());
}
 
?>

With this we conclude this post. It will be quite helpful if you go over the below references if you are unfamiliar with the Google Analytics API.

Update

Webresourcesdepot features a nifty little application using the above to dispay the Google pageviews in a Feed-burner style chicklet display.

References:
a. Google Analytics Data API – Data Feed
b. Dimensions & Metrics Reference
c. Filters

As you can see it is blazingly fast, being twice as fast as Firefox 3 and twenty times faster than Internet Explorer 6.  If you are using JavaScript heavy applications like Gmail or Javascript UI frameworks like Yahoo UI, extJS, jQuery etc. than you can really reap the benefits of a fast engine. If you like to see a visual comparison try running one of John Resig’s Processing.js demo in Firefox 3 and Chrome and you can see how fast Chrome can run JavaScript.

Some of the other interesting things Google Chrome offers can be read in a comic format here – designed by the brilliant Scott McCloud, a sample page is shown below.

You can download Google Chrome here.