search

Stichoza / google-translate-php

🔤 Free Google Translate API PHP Package. Translates totally free of charge.
MIT License
1.8k stars 380 forks source link
detect-language google-translate language-detection php translate translation

readme

Google Translate PHP

Latest Stable Version Total Downloads Downloads Month Petreon donation PayPal donation

Free Google Translate API PHP Package. Translates totally free of charge.

Installation

Install this package via Composer.

composer require stichoza/google-translate-php

Note PHP 8.0 or later is required. Use following versions of this package for older PHP versions:

Package version PHP Version Documentation
^5.1 PHP >= 8.0 v5 Docs
^4.1 PHP >= 7.1 v4 Docs
^3.2 PHP < 7.1 v3 Docs

Basic Usage

Create GoogleTranslate object

use Stichoza\GoogleTranslate\GoogleTranslate;

$tr = new GoogleTranslate('en'); // Translates into English

Or you can change languages later

$tr = new GoogleTranslate(); // Translates to 'en' from auto-detected language by default
$tr->setSource('en'); // Translate from English
$tr->setSource(); // Detect language automatically
$tr->setTarget('ka'); // Translate to Georgian

Translate sentences

echo $tr->translate('Hello World!');

Also, you can also use method chaining

echo $tr->setSource('en')->setTarget('ka')->translate('Goodbye');

Or call a shorthand static method trans

echo GoogleTranslate::trans('Hello again', 'ka', 'en');

Advanced Usage

Language Detection

To detect language automatically, just set the source language to null:

$tr = new GoogleTranslate('es', null); // Or simply do not pass the second parameter 
$tr->setSource(); // Another way

Use getLastDetectedSource() to get detected language:

$tr = new GoogleTranslate('fr');

$text = $tr->translate('Hello World!');

echo $tr->getLastDetectedSource(); // Output: en

Return value will be null if the language couldn't be detected.

Supported Languages

You can get a list of all the supported languages using the languages method.

$tr = new GoogleTranslate();

$languages = $tr->languages(); // Get supported languages in iso-639 format

// Output: [ 'ab', 'ace', 'ach', 'aa', 'af', 'sq', 'alz', ... ]

Optionally, pass a target language code to retrieve supported languages with names displayed in that language.

$tr = new GoogleTranslate();

$languages = $tr->languages('en'); // Get supported languages, display name in english
// Output: [ 'en' => English', 'es' => 'Spanish', 'it' => 'Italian', ... ]

echo $languages['en']; // Output: 'English'
echo $languages['ka']; // Output: 'Georgian'

Same as with the translate/trans methods, you can also use a static langs method:

GoogleTranslate::langs();
// Output: [ 'ab', 'ace', 'ach', 'aa', 'af', 'sq', 'alz', ... ]

GoogleTranslate::langs('en');
// Output: [ 'en' => English', 'es' => 'Spanish', 'it' => 'Italian', ... ]

Supported languages are also listed in Google API docs.

Preserving Parameters

The preserveParameters() method allows you to preserve certain parameters in strings while performing translations. This is particularly useful when dealing with localization files or templating engines where specific placeholders need to be excluded from translation.

Default regex is /:(\w+)/ which covers parameters starting with :. Useful for translating language files of Laravel and other frameworks. You can also pass your custom regex to modify the parameter syntax.

$tr = new GoogleTranslate('de');

$text = $tr->translate('Page :current of :total'); // Seite :aktuell von :gesamt

$text = $tr->preserveParameters()
           ->translate('Page :current of :total'); // Seite :current von :total

Or use custom regex:

$text = $tr->preserveParameters('/\{\{([^}]+)\}\}/')
           ->translate('Page {{current}} of {{total}}'); // Seite {{current}} von {{total}}

You can use same feature with static trans() method too.

GoogleTranslate::trans('Welcome :name', 'fr', preserveParameters: true); // Default regex

GoogleTranslate::trans('Welcome {{name}}', 'fr', preserveParameters: '/\{\{([^}]+)\}\}/'); // Custom regex

Using Raw Response

For advanced usage, you might need the raw results that Google Translate provides. you can use getResponse method for that.

$responseArray = $tr->getResponse('Hello world!');

Custom URL

You can override the default Google Translate url by setUrl method. Useful for some countries

$tr->setUrl('http://translate.google.cn/translate_a/single');

HTTP Client Configuration

This package uses Guzzle for HTTP requests. You can pass an array of guzzle client configuration options as a third parameter to GoogleTranslate constructor, or just use setOptions method.

You can configure proxy, user-agent, default headers, connection timeout and so on using this options.

$tr = new GoogleTranslate('en', 'ka', [
    'timeout' => 10,
    'proxy' => [
        'http'  => 'tcp://localhost:8125',
        'https' => 'tcp://localhost:9124'
    ],
    'headers' => [
        'User-Agent' => 'Foo/5.0 Lorem Ipsum Browser'
    ]
]);
// Set proxy to tcp://localhost:8090
$tr->setOptions(['proxy' => 'tcp://localhost:8090'])->translate('Hello');

// Set proxy to socks5://localhost:1080
$tr->setOptions(['proxy' => 'socks5://localhost:1080'])->translate('World');

For more information, see Creating a Client section in Guzzle docs.

Custom Token Generator

You can override the token generator class by passing a generator object as a fourth parameter of constructor or just use setTokenProvider method.

Generator must implement Stichoza\GoogleTranslate\Tokens\TokenProviderInterface.

use Stichoza\GoogleTranslate\Tokens\TokenProviderInterface;

class MyTokenGenerator implements TokenProviderInterface
{
    public function generateToken(string $source, string $target, string $text): string
    {
        // Your code here
    }
}

And use:

$tr->setTokenProvider(new MyTokenGenerator);

Translation Client (Quality)

Google Translate has a parameter named client which defines quality of translation. First it was set to webapp but later google added gtx value which results in a better translation quality in terms of grammar and overall meaning of sentences.

You can use ->setClient() method to switch between clients. For example if you want to use older version of translation algorithm, type $tr->setClient('webapp')->translate('lorem ipsum...'). Default value is gtx.

Errors and Exception Handling

Static method trans() and non-static translate() and getResponse() methods will throw following exceptions:

As of v5.1.0 concrete exceptions are available in \Stichoza\GoogleTranslate\Exceptions namespace:

All concrete exceptions are backwards compatible, so if you were using older versions, you won't have to update your code.

TranslationDecodingException extends UnexpectedValueException, while LargeTextException, RateLimitException and TranslationRequestException extend ErrorException that was used in older versions (<5.1.0) of this package.

In addition, translate() and trans() methods will return null if there is no translation available.

Known Limitations

Disclaimer

This package is developed for educational purposes only. Do not depend on this package as it may break anytime as it is based on crawling the Google Translate website. Consider buying Official Google Translate API for other types of usage.

Donation

If this package helped you reduce your time to develop something, or it solved any major problems you had, feel free to give me a cup of coffee :)