Translating Text Using the Google Translate API and PHP, JSON and cURL

Google Translate is a service from Google that you can use to translate text or HTML from one language to another. One of the great features of this service is that they now offer an API to let you programmatically translate text. In this article I will show you how to interact with the Google Translate API.

Initially, the Google Translate API was available only via JavaScript. This has now changed, as version 2 offers a REST interface which returns translations in JSON format.

To use this API you must have a Google API key. More information about this is available at Google Translate V2 Developer Guide.

Note: At time of writing, there is a limit for non-paying customers of 100,000 characters translated per day.

The API at this stage contains three available operations: retrieve a list of available language pairs (languages), translate text (translate), and determine the language of text (detect). In this article I’ll show you how to use the translate operation.

All API calls are made to the endpoint https://www.googleapis.com/language/translate/v2.

Input Parameters

To translate text, the following parameters are used:

• key – This is your Google API key
• source – The language of the string being translated (e.g. en for English)
• target – The language you want the text translated to (e.g. es for Spanish)
• q – The text to translate. This can be HTML code if you’re trying to translate a HTML document

If you omit the source parameter, the API will attempt to determine the input language automatically. If you know what language is being used you should specify it so no mistakes are made (especially in cases where short ambigous phrases are being used).

Query Limits

Because this API is designed to used via a “GET” request, long documents cannot be translated (since there is a character limit for these types of requests).

The good news is that Google allows a way to get around this by “faking” a GET request using a POST request. This is achieved by sending the HTTP header X-HTTP-Method-Override: GET. I will show you how to do this in the code below.

Handling Results

The data returned by this API is in JSON format. You can decode this data using the PHP json_decode() function. Once you’ve converted this response data to a PHP array, you can access the $arr[‘data’][‘translations’] key to read the translation data.

Note: This element is an array, since it is possible to translate multiple texts in a single API call (this is achieved by including the q parameter multiple times). This array will contain an element for each translated text.

Another thing to be aware of is that foreign languages will typically use an extended character set. Be sure to handle this correctly.

For instance, if you’re translating a HTML, certain characters may not be displayed correctly in the translation if you don’t include a header such as <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

Translating Text With LanguageTranslator

The following code is a simple class I created to demonstrate how easy the API is to use. There are some improvements that can be made, as noted at the end of this article, but this is definitely enough to get started.

I’ve included a number of comments in the code to explain how it works.

Listing 1 A PHP class to translate text using Google Translate (LanguageTranslator.php)

<?php
class LanguageTranslator
{
// this is the API endpoint, as specified by Google
const ENDPOINT = 'https://www.googleapis.com/language/translate/v2';

// holder for you API key, specified when an instance is created
protected $_apiKey;

// constructor, accepts Google API key as its only argument
public function __construct($apiKey)
{
$this->_apiKey = $apiKey;
}

// translate the text/html in $data. Translates to the language
// in $target. Can optionally specify the source language
public function translate($data, $target, $source = '')
{
// this is the form data to be included with the request
$values = array(
'key'    => $this->_apiKey,
'target' => $target,
'q'      => $data
);

// only include the source data if it's been specified
if (strlen($source) > 0) {
$values['source'] = $source;
}

// turn the form data array into raw format so it can be used with cURL
$formData = http_build_query($values);

// create a connection to the API endpoint
$ch = curl_init(self::ENDPOINT);

// tell cURL to return the response rather than outputting it
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// write the form data to the request in the post body
curl_setopt($ch, CURLOPT_POSTFIELDS, $formData);

// include the header to make Google treat this post request as a get request
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-HTTP-Method-Override: GET'));

// execute the HTTP request
$json = curl_exec($ch);
curl_close($ch);

// decode the response data
$data = json_decode($json, true);

// ensure the returned data is valid
if (!is_array($data) || !array_key_exists('data', $data)) {
throw new Exception('Unable to find data key');
}

// ensure the returned data is valid
if (!array_key_exists('translations', $data['data'])) {
throw new Exception('Unable to find translations key');
}

if (!is_array($data['data']['translations'])) {
throw new Exception('Expected array for translations');
}

// loop over the translations and return the first one.
// if you wanted to handle multiple translations in a single call
// you would need to modify how this returns data
foreach ($data['data']['translations'] as $translation) {
return $translation['translatedText'];
}

// assume failure since success would've returned just above
throw new Exception('Translation failed');
}
}
?>

Using the LanguageTranslator Class

The following code shows you can use this class. Be sure to replace the API key and input text as required. This is a crude example that will read English text from a file, translate it to German, then output it to a file.

Listing 2 Making use of the LanguageTranslator class (listing-2.php)

<?php
require_once('LanguageTranslator.php');

$yourApiKey = '';

$sourceData = file_get_contents('/file/to/path.txt');
$source = 'en';

$target = 'de';

$translator = new LanguageTranslator($yourApiKey);

$targetData = $translator->translate($sourceData, $source, $target);
file_put_contents($targetData, 'file.txt-' . $target);
?>

Further Exercises

There are several ways this code can be improved. See if you can make these improvements:

1. Modify the code so multiple texts can be translate in a single call. This is achieved by including the q parameter once for every text. You must then also return all of the corresponding translations.
2. Change the code so it returns the automatically-detected source language if the user did not specify the source language. This is returned in the detectedSourceLanguage value for a given translation.
3. Handle different kinds of errors appropriately. For instance, this code doesn’t differentiate between an input error and being over usage quota