Integrating Google Translate API with Yii2

In this post, I'll be sharing how to integrate the Google Translate API with Yii2. As developers, we often encounter challenges when building multilingual sites with translation capabilities. Whether we're manually adding them or relying on a CMS, the process can be incredibly time-consuming and tedious.

Although it is not perfect, the Google Translate API has a high accuracy level, comprehensive language support and is constantly being updated to ensure relatability. Hopefully by the end of this guide, you'll be able to incorporate Google Translate into your Yii2 application.

Adding Google Translate API Configuration to Yii2

Before we start translating text, we need to configure the Google Translate API in our Yii2 application. Follow these steps to set up the API configuration:

Step 1: Obtain Your API Key

If you haven't already, refer to the previous post on setting up a Google Cloud Project and enabling the Google Translate API. Once you have your API key, proceed with the following steps.

Step 2: Configure Yii2 to Use the API Key

Open your Yii2 configuration file (common/config/main.php) and add the API key to the params section:

`<?php

return [
    'params' => [
        'google' => [
            'translate' => [
                'api_key' => 'YOUR_API_KEY_HERE', // Replace with your actual API key
                'enabled' => true,
            ],
        ],
    ],
    // Other configurations
];`

Using the API to Translate Text

Now that we've configured our application to use the Google Translate API, let's create a function that uses the API to translate text. We'll create a new component to encapsulate this functionality.

Step 1: Create the Translate Component

Create a new file components/GoogleTranslate.php and add the following code:

<?php

namespace common\components;

use Yii;
use yii\base\Component;

class GoogleTranslate extends Component {

    /**
     * Translates text using the Google Translate API.
     *
     * @param string $text The text to be translated.
     * @param string $targetLanguage The language to translate the text into.
     * @param string $sourceLanguage The language of the text to be translated (default: 'en').
     * @return string The translated text.
     * @throws \Exception If Google Translate API is not enabled or if an error occurs during translation.
     */
    public function translate($text, $targetLanguage, $sourceLanguage = 'en') {
        // Check if Google Translate API is enabled
        if (!Yii::$app->params['google']['translate']['enabled']) {
            throw new \Exception("Google Translate is not enabled.");
        }

        // Get the API key from Yii2 application parameters
        $apiKey = Yii::$app->params['google']['translate']['api_key'];
        // Construct the API request URL
        $url = "https://translation.googleapis.com/language/translate/v2?key={$apiKey}";

        // Prepare data for the API request
        $data = [
            'q' => $text,
            'source' => $sourceLanguage,
            'target' => $targetLanguage,
            'format' => 'text',
        ];

        // Initialize a cURL session
        $ch = curl_init();
        // Set cURL options for the API request
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        // Execute the cURL request and get the response
        $response = curl_exec($ch);
        // Close the cURL session
        curl_close($ch);

        // Process the API response
        return $this->handleResponse($response);
    }

    /**
     * Handles the response received from the Google Translate API.
     *
     * @param string $response The API response in JSON format.
     * @return string The translated text.
     * @throws \Exception If an error occurs while processing the response.
     */
    private function handleResponse($response) {
        // Decode the JSON response into an associative array
        $response = json_decode($response, true);

        // Check if decoding was successful
        if ($response === null) {
            throw new \Exception("Failed to decode JSON response.");
        }

        // Check if the response contains an error message
        if (isset($response['error'])) {
            // Extract the error message
            $errorMessage = $response['error']['message'];
            // Throw an exception indicating a Google Translate API error
            throw new \Exception("Google Translate API error: {$errorMessage}");
        }

        // Return the translated text extracted from the response data
        return $response['data']['translations'][0]['translatedText'];
    }
}

This component defines a translate method that sends a translation request to the Google Translate API and a handleResponse method that processes the API response.

Step 2: Register the Component

Open your Yii2 configuration file (common/config/main.php) and register the GoogleTranslate component:

<?php

return [
    'components' => [
        'googleTranslate' => [
            'class' => 'common\components\GoogleTranslate',
        ],
    ],
    // Other configurations
];

Yii2 follows the dependency injection design pattern, where component can be injected into other classes and componentes when needed. So by doing this, we enable Yii2 to automatically inject an instance of GoogleTranslate into classes that require the translation functionality.

Handling API Responses and Errors

Handling API responses and errors is crucial to ensure a smooth user experience and to debug issues effectively. Let's look at how the GoogleTranslate component handles responses and errors.

Response Handling

The handleResponse method decodes the JSON response and checks for errors. If the response contains a translation, it returns the translated text. If there is an error, it throws an exception with a detailed error message.

Error Handling

Here are a few common scenarios and how to handle them:

Invalid API Key: Ensure your API key is correct and has the necessary permissions. If the API key is invalid, Google will return an error which the handleResponse method will catch and throw as an exception.

API Quota Exceeded: Google Translate API has usage limits. If you exceed these limits, you'll receive an error response. Consider implementing retry logic or monitoring usage to prevent exceeding quotas.

Network Issues: If there's a network issue, curl_exec might fail. Ensure you handle such cases gracefully, possibly with retries or alternative actions.

Example Usage

Let's see how to use the GoogleTranslate component in a controller to translate text:

<?php

namespace frontend\controllers;

use Yii;
use yii\web\Controller;

class TranslateController extends Controller {

    public function actionIndex() {
        try {
            $text = 'Hello, world!';
            $targetLanguage = 'es'; // Spanish
            $translatedText = Yii::$app->googleTranslate->translate($text, $targetLanguage);
            return $this->render('index', ['translatedText' => $translatedText]);
        } catch (\Exception $e) {
            Yii::error($e->getMessage(), __METHOD__);
            return $this->render('error', ['message' => $e->getMessage()]);
        }
    }
}

In the actionIndex method, we use the googleTranslate component to translate "Hello, world!" into Spanish. If an error occurs, it is caught, logged, and an error message is displayed.

Conclusion

By following this guide, you can add automated translation capabilities to your Yii2 application. This enhances your applications ability to support multiple languages and reach a broader audience.

I have plans to make this into a mini series, where we'll be next exploring how to create and run translation jobs in Yii2. This will allow for asynchronous and scalable translation processing.

Resources:
Google PHP Client Library Documentation
Yii2 Internationalization Documentation
Dependency Injection Container