Skip to main content

Google Translate

The Google Translate module provides GoogleTranslate for text translations through Google Cloud Translation v2.

Use it when an application needs server-side translation without adding application-specific translation handling.

Install​

composer require qore-next/google-translate

The package auto-discovers GoogleTranslateServiceProvider.

No migrations, config or routes are published by this module. Install it, enable it in the modules UI and configure the API key before using translations in production.

Usage​

Use the google_translate() helper:

use function Qore\Next\GoogleTranslate\Helpers\google_translate;

$googleTranslate = google_translate();

Or resolve the GoogleTranslate service from the container:

use Qore\Next\GoogleTranslate\Services\GoogleTranslate;

$googleTranslate = app(GoogleTranslate::class);

Basic usage:

use Qore\Next\GoogleTranslate\Enums\GoogleTranslateLanguage;

$result = $googleTranslate->translate(
    text: 'Hello world',
    targetLanguage: GoogleTranslateLanguage::DUTCH,
);

$result->translatedText;

Translate HTML input while preserving tags:

use Qore\Next\GoogleTranslate\Enums\GoogleTranslateFormat;
use Qore\Next\GoogleTranslate\Enums\GoogleTranslateLanguage;

$result = $googleTranslate->translate(
    text: '<p>Hello world</p>',
    targetLanguage: GoogleTranslateLanguage::DUTCH,
    format: GoogleTranslateFormat::HTML,
);

$result->translatedText;

Translate multiple texts while preserving the input keys:

$results = $googleTranslate->translateMany(
    texts: [
        'title' => 'Hello world',
        'subtitle' => 'Good morning',
    ],
    targetLanguage: GoogleTranslateLanguage::DUTCH,
    sourceLanguage: GoogleTranslateLanguage::ENGLISH,
);

$results['title']->translatedText;

translate() returns a GoogleTranslateResult. translateMany() returns an array of GoogleTranslateResult objects with the same keys and order as the input texts.

translateMany() accepts at most 128 texts per call. Empty texts are returned without making a Google API request for those items. Non-empty translations are cached per text for one day. When a later translateMany() call contains cached texts, only the uncached translations are sent to Google. Duplicate uncached texts inside the same call are only sent once and mapped back to every matching input key. If Google returns fewer translations than requested, the service throws an exception.

The service accepts GoogleTranslateLanguage enum cases for languages and GoogleTranslateFormat enum cases for the input format. GoogleTranslateFormat::TEXT is for plain text. GoogleTranslateFormat::HTML is for HTML input where Google should preserve tags while translating the text content. When sourceLanguage is omitted, Google detects it and returns the detected language on GoogleTranslateResult::$detectedSourceLanguage when available. Detected languages and supported language results are returned as enums.

The optional $model argument selects the Google translation model. Leave it empty for Google's default model, pass GoogleTranslateModel::NMT or GoogleTranslateModel::BASE for fixed Basic API values, or pass the Translation LLM resource name when you want Google's LLM model:

use Qore\Next\GoogleTranslate\Enums\GoogleTranslateLanguage;
use Qore\Next\GoogleTranslate\Enums\GoogleTranslateModel;

$result = $googleTranslate->translate(
    text: 'Hello world',
    targetLanguage: GoogleTranslateLanguage::DUTCH,
    model: GoogleTranslateModel::translationLlm('my-project', 'global'),
);

$result->translatedText;

You can also read supported languages or detect a single source language:

use Qore\Next\GoogleTranslate\Enums\GoogleTranslateLanguage;

$languages = $googleTranslate->supportedLanguages(targetLanguage: GoogleTranslateLanguage::ENGLISH);
$language = $googleTranslate->detectLanguage('Goedemorgen');

Configure​

Enable the module in Qore's modules UI, then save the Google API key in the module settings.

The key is stored as:

qore()->settings()->getSetting('google-translate.api_key');

The settings form validates the key with a small Google Cloud Translation request.