google-translate-php: translating through Google's web endpoint with no API key

The API surface, and how little of it there is

Stichoza's google-translate-php is a free Google Translate API PHP package that translates totally free of charge, and the whole public surface fits in a few methods.

You construct an object with the target language:

use Stichoza\GoogleTranslate\GoogleTranslate;

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

and then either change the languages later or leave the source open for detection:

$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

The translation call is a single method, and the setters return the object, so they chain:

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

And there is a static shorthand for the one-off case, where the arguments are the text, the target and the source:

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

The target-first constructor signature is worth noticing, because it is the kind of thing that catches people out. `new GoogleTranslate('en')` means translate into English, not from English, and the source defaults to auto-detection. That is a deliberate design, since a caller with no particular source language in mind is the common case, but it is the opposite of the order most translation libraries use.

The package is on Packagist under `stichoza/google-translate-php`, is MIT licensed, and the current version is 5.3.5 with the last push on 2026-09-20.

Guzzle options, the URL override, and the raw response

The HTTP layer is Guzzle, and the package exposes it, which is the right choice for a library that has to work behind proxies and in odd network environments.

You can pass an array of Guzzle client configuration options as a third parameter to the `GoogleTranslate` constructor, or use the `setOptions` method. The documentation lists proxy, user-agent, default headers, connection timeout and so on as the things you can configure:

$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'
    ]
]);

That set of options is a tell about how the library works. A proxy configuration, a browser-like user agent and a timeout are the three things you need when calling an endpoint that expects a browser, and exposing them as first class options means a project behind a corporate proxy can still use it.

The URL override is the escape hatch for the same reason:

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

The documentation says this is useful for some countries, and that is the real reason it exists. The endpoint the package calls by default is not reachable from everywhere, and the regional variant is. Being able to point the client at the other host without patching the library is what makes the package work from a server in a particular region.

For advanced usage, the `getResponse` method gives you the raw results that Google Translate provides:

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

The raw array is where the parts the wrapper does not surface live, the detection confidence, the alternative translations, the pronunciation fields, and a caller that needs them would otherwise have to dig through the wrapper's output.

The documentation also has sections on a custom token generator and on errors and exception handling, which are the two places where a package like this is most likely to differ between versions.

Detection, the language list, and preserving placeholders

Three features go beyond the basic call, and the third is the one that makes it usable in a real application.

Language detection works by setting the source to null, either in the constructor or with `setSource()`:

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

And the detected language is available afterwards with `getLastDetectedSource()`, which returns null if the language could not be detected:

$tr = new GoogleTranslate('fr');
$text = $tr->translate('Hello World!');
echo $tr->getLastDetectedSource(); // Output: en

The supported language list comes from the `languages` method, which returns ISO 639 codes, and passing a target language code returns the list keyed by code with the names in that language:

$languages = $tr->languages(); // Get supported languages in iso-639 format
$languages = $tr->languages('en'); // Get supported languages, display name in english
echo $languages['ka']; // Output: 'Georgian'

The same is available statically as `GoogleTranslate::langs()` and `GoogleTranslate::langs('en')`, and the same list is published in the Google API documentation.

The third feature is the one that matters for a localisation workflow. The `preserveParameters()` method allows you to preserve certain parameters in strings while performing translations, and it is particularly useful when dealing with localization files or templating engines where specific placeholders need to be excluded from translation.

$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

The default regex is `:(\w+)`, which covers parameters starting with a colon, and it is described as useful for translating language files of Laravel and other frameworks. A custom regex changes the syntax:

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

That is a genuinely useful piece of engineering. A machine translator will happily translate the words inside a placeholder, and the translation then no longer matches the template variable the code expects. Masking them before the call and unmasking after is the standard workaround, and having it in the library with a configurable pattern saves every project from writing it.

What the disclaimer says, and why it is the first thing to read

The documentation's own table of contents puts Known Limitations and Disclaimer at the end, but they are the first thing to read.

The premise is worth stating plainly, because it is what the whole package rests on. This package calls the same endpoint that the Google Translate web page uses, rather than the paid Cloud Translation API. There is no API key, no project, no billing account, and therefore no cost and no quota negotiation. That is the entire appeal, and it is also the entire risk.

The endpoint is not a supported API. Google can change it without notice, it can throttle it, and it can treat traffic from a data centre differently from traffic from a browser. The package's mitigations are the ones you can see in the API: the Guzzle options for proxy and user agent, the URL override for regional availability, the error handling section, and the raw response accessor. Those are the tools you need to keep working when the endpoint misbehaves, but they cannot make an unsupported endpoint supported.

So the sensible way to think about it is that this is a library for a side feature, and the paid Cloud Translation API is the answer when translation is what the product does. The cost difference is not the issue, since this one is free, it is the durability. A translation feature that breaks on a Tuesday because an internal endpoint changed is a support ticket, and if you are translating user-facing content at volume the difference between a supported API and an undocumented one is the difference between a feature and an outage.

The other thing to know is the versioning, which shows a long history of maintaining PHP compatibility. PHP 8.0 or later is required for the current line, and the table gives the branches for older installations: `^5.1` for PHP 8.0 and up, `^4.1` for PHP 7.1 and up, and `^3.2` for PHP below 7.1, each with its own documentation branch. A package that has shipped four major lines in parallel and kept them documented is a package whose maintainer takes compatibility seriously, which is a good signal, and it also means the version you install depends on the PHP you have rather than on what is newest.

The version matrix and the project layout

The repository layout reflects a conventional PHP package with modern tooling: a `composer.json`, a `phpstan.neon.dist` for static analysis, a `phpunit.xml.dist` for the test suite, an `src/` and `tests/` split, an `.editorconfig` and a `CONTRIBUTING.md`.

The maintenance pattern across the PHP versions is worth noticing on its own. A package that has shipped four major lines in parallel and kept each of them documented is a package whose maintainer treats compatibility as part of the work, and it also means the version you install depends on the PHP you already have rather than on what is newest.

The release history shows the same steady rhythm. Versions 5.3.3, 5.3.4 and 5.3.5 came out in August and September 2026, and the last push was on 2026-09-20.

Editorial conclusion

google-translate-php fits a PHP application that needs machine translation as a side feature, such as a moderation preview or a content pipeline, because there is no key to provision and no account to bill, and because the API is small enough to read in one sitting. Skip it if translation is your product's core dependency, since the package's own disclaimer notes the endpoint is not an official API and that it may stop working or throttle, and use the paid Cloud Translation API for that. Before you ship it, read the known limitations and the disclaimer in the documentation, and note the PHP version floor of 8.0, with the 5.1, 4.1 and 3.2 lines kept for older installations. The last push was on 2026-09-20 with version 5.3.5.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Stichoza/google-translate-php on GitHub