Installed in one line.

The service provider is auto-discovered. There is nothing to register, nothing to migrate and nothing to publish before it works.

Install the package

$ composer require gabrielesbaiz/google-translate-toolkit

Publish the configuration

Optional, but you will want it the moment you set a glossary or a budget.

$ php artisan vendor:publish --tag="google-translate-toolkit-config"

Add your key

GOOGLE_TRANSLATE_API_KEY=your-cloud-console-key
GOOGLE_TRANSLATE_TARGET=it
# GOOGLE_TRANSLATE_SOURCE is deliberately left empty:
# Google detects the source language, which costs the same
# and is more accurate than guessing.

Getting an API key

1. Open the Google Cloud console and select or create a project.
2. Enable Cloud Translation API under APIs & Services → Library.
3. Create an API key under APIs & Services → Credentials.
4. Restrict it: API restrictions → Cloud Translation API, plus an IP restriction if your servers have fixed addresses.

Verify

$ php artisan translate:text "Hello world" --to=it

 from   to   source        translation   origin
 auto   it   Hello world   Ciao mondo    api

Five minutes, start to finish.

Two facade names are registered and both resolve the same instance: GoogleTranslateToolkit (the 1.x name) and GoogleTranslate.

Translate something

use Gabrielesbaiz\GoogleTranslateToolkit\Facades\GoogleTranslate;

// The short way — source auto-detected, target from config
GoogleTranslate::justTranslate('The message bounced');
// "Il messaggio è stato rifiutato"

// The full object
$translation = GoogleTranslate::translate('Good morning');

$translation->translatedText;   // "Buongiorno"
$translation->sourceLanguage;   // "en" — detected by Google
$translation->cached;           // false now, true next time
(string) $translation;          // "Buongiorno"

The builder

Every modifier returns a new instance, so a configured builder is safe to store and reuse. Nothing happens until a terminal method runs.

$italian = GoogleTranslate::from('en')->to('it');

$italian->text('Hello');                 // string
$italian->asHtml()->text($post->body);  // a different builder
$italian->many(['one', 'two']);          // TranslationCollection

// Many languages, one pooled fan-out
GoogleTranslate::to(['it', 'fr', 'de'])->translate('Good morning');
// Collection keyed by locale

What comes back

Terminal methods

Every key, and why it exists.

Every setting has a working default. Delete the ones you do not care about — the package falls back to what is documented here.

Credentials and defaults

'api_key'  => env('GOOGLE_TRANSLATE_API_KEY', env('GOOGLE_DEVELOPER_KEY')),
'base_url' => env('GOOGLE_TRANSLATE_BASE_URL', 'https://translation.googleapis.com/language/translate/v2'),

'default_source' => env('GOOGLE_TRANSLATE_SOURCE'),   // null = auto-detect
'default_target' => env('GOOGLE_TRANSLATE_TARGET'),   // null = app.locale
'default_format' => 'text',                          // or 'html'
'strict_languages' => true,

HTTP and chunking

Cache, limits and resilience

Language codes

Codes are normalised before anything else happens: ZH_tw, zh-tw and zh-TW are the same language. With strict_languages on, an unknown code throws UnsupportedLanguageException rather than spending a request to find out.

use Gabrielesbaiz\GoogleTranslateToolkit\Enums\Language;

Language::Italian->value;               // "it"
Language::ChineseTraditional->label();  // "Chinese (Traditional)"
Language::Arabic->isRtl();               // true — 9 of the 137 are
Language::normalize('ZH_tw');            // "zh-TW"
Language::options();                     // Collection<code, label> for a select

The part other packages get wrong.

Google will happily translate :name, reorder %s, break {{ $blade }} and put a space in the middle of a URL. This package masks those before the call and restores them after.

GoogleTranslate::justTranslate(
    'Welcome back, :name — {count} items at https://example.com'
);
// "Bentornato, :name — {count} articoli su https://example.com"

What is shielded out of the box

In plain-text mode the mask is ⟦0⟧; in HTML mode it is <span translate="no">0</span>, which Google is obliged to leave alone. Restoration is tolerant: if a space appears inside the sentinel, the package still finds it.

Adding your own

// Per call — a regex, or a literal that gets quoted for you
GoogleTranslate::preserving(['/#[A-Za-z0-9_]+/', 'Acme Mailer'])
    ->text($post->body);

// Globally
'placeholders' => [
    'enabled'  => true,
    'patterns' => ['/\[\[.*?\]\]/'],
],

// Off, when you know the text is plain prose
GoogleTranslate::query()->withoutPreserving()->text($text);

Glossary

Two different jobs share one config section. Protected terms are masked like a placeholder and never reach Google at all. Overrides are applied after the translation comes back, so you can force domain wording Google gets wrong.

'glossary' => [
    'protect' => ['Acme', 'Acme Mailer'],

    'overrides' => [
        'it' => [
            'rimbalzo' => 'rifiuto',
            'consegna fallita' => 'mancata consegna',
        ],
    ],
],

Checking the result

Back-translation is the cheapest useful check there is: translate out, translate back, and score how much meaning survived.

$check = GoogleTranslate::roundTrip('The message was rejected', via: 'it');

$check->translated;          // "Il messaggio è stato rifiutato"
$check->back;                // "The message was rejected"
$check->score;               // 1.0
$check->isSuspicious(0.6);   // false

Most translations never leave your server.

Translations are deterministic enough to cache, and caching them is the single biggest thing this package does for your bill.

How a batch is split

A batch is partitioned, not cached whole. Hits are served locally, and only the misses are sent — so adding one new string to a hundred old ones costs one string.

GoogleTranslate::translateBatch(['one', 'two']);          // 1 request, 2 segments
GoogleTranslate::translateBatch(['one', 'two', 'three']); // 1 request, 1 segment

$t = GoogleTranslate::translate('one');
$t->cached;   // true — it never went out

The key is sha1(source|target|format|text) under cache.prefix. Source, target and format are all part of it, so text and html are separate entries — as are two different target languages for the same string.

Controlling it

GoogleTranslate::withoutCache()->text('Hello');       // always calls
GoogleTranslate::withCache(ttl: 3600)->text('Hello'); // one hour

GoogleTranslate::flushCache();   // bumps a namespace version
// php artisan translate:cache-clear

// Pre-fill before a launch, on the queue
GoogleTranslate::warm($strings, ['it', 'de', 'fr']);

Knowing the cost first

Google bills per million characters, per target language. Fan-out multiplies: three targets is three times the characters.

$estimate = GoogleTranslate::estimate($texts, ['it', 'fr']);

$estimate->segments;             // 128
$estimate->characters;           // 8 402
$estimate->billableCharacters;   // 16 804 — two targets
$estimate->cachedSegments;       // 31 already answered locally
$estimate->requests;             // 4
$estimate->formattedCost();      // "USD 0.3361"

A ceiling that holds

'budget' => ['max_characters_per_day' => 500_000],

Watching the spend

 date         calls  characters  cache hits  hit rate  cost
 2026-09-20      41      62 118         388    90.4%   $1.24
 2026-09-21      12      18 402         419    97.2%   $0.37
 2026-09-22       9      11 088         402    97.8%   $0.22
 2026-09-23       6       7 640         511    98.8%   $0.15

The same numbers are available in code through GoogleTranslate::stats(7), and the raw counters through usage().

When Google has a bad minute

// Throw — the default
GoogleTranslate::justTranslate($text);

// Return the source text instead, and carry on
GoogleTranslate::onFailUseSource()->text($text);

// Or globally, for every call
'fallback_to_source' => true,

Text handed back by the fallback is never written to the cache. It was never translated, so storing it would serve the source language for the whole 30-day lifetime after a single bad minute. The segment stays a miss, and the next call tries again.

Everything extends GoogleTranslateException, which extends RuntimeException — so catching \Exception still works exactly as it did in 1.x.

One column, one locale.

The convention is a sibling column per language — body and body_it — which is what most applications already do by hand.

The trait

use Gabrielesbaiz\GoogleTranslateToolkit\Concerns\HasTranslations;
use Gabrielesbaiz\GoogleTranslateToolkit\Contracts\Translatable;

class Message extends Model implements Translatable
{
    use HasTranslations;

    public function translatableAttributes(): array
    {
        return ['body'];   // → body_it
    }
}

Filling the columns

$message->translateAttributes()->save();                  // default locale
$message->translateAttributes(to: 'de', from: 'en')->save();
$message->translateAttributes(overwrite: true)->save();   // redo it

$message->queueTranslateAttributes('it');                  // off to the queue

$message->getTranslatedAttribute('body', 'it');
$message->translatedAttributeName('body', 'it');
// "body_it"

Finding what is missing

Message::query()->whereTranslationMissing('body')->count();
Message::query()->whereTranslationMissing('body', 'de')->get();

The scope matches rows where the source column has content and the translated column does not — which is exactly what translate:model walks.

Backfilling a table

$ php artisan translate:model "App\Models\Message" --to=it --chunk=500
$ php artisan translate:model "App\Models\Post" --to=de --queue --limit=2000

After the response, not during it

For a webhook that must answer in milliseconds, deferred() runs the translation once the response has been sent, using Laravel's defer().

GoogleTranslate::deferred()->translate($description, function ($translation) use ($message) {
    $message->update(['body_it' => $translation->translatedText]);
});

Events

recovered is true when the failure was absorbed by onFailUseSource() — useful for a log line that distinguishes "degraded" from "broken". A recovered result is not cached, so the next call retries rather than serving the source text for the rest of the TTL.

Every method, in one place.

The facade proxies a single singleton. Anything that opens a builder returns a PendingTranslation; anything that ends one returns data.

Opening a builder

Translating and detecting

Languages, quality and cost

Data objects

Blade, macros and helpers

{{-- target first, source second --}}
@translate($post->title)
@translate($post->title, 'fr')
@translate($post->title, 'fr', 'en')
@translateHtml($post->body, 'fr')

Str::translate('hello', 'fr');
str('hello')->translateTo('de')->upper();
str('bonjour')->detectLanguage();        // "fr"
collect(['a', 'b'])->translate('fr');
google_translate('hello', 'es');

Validation and casting

$request->validate([
    'locale' => ['required', Rule::language()],
    'target' => ['required', Rule::language(['it', 'en', 'fr'])],
]);

protected function casts(): array
{
    return ['locale' => AsLanguage::class];   // Language enum in, ISO code out
}

Swapping the driver

Bind anything implementing the Translator contract — a different provider, an on-premise model, or a canned dataset for a demo tenant. Cache, placeholders, glossary, budget, events, Eloquent and the commands all keep working on top of it.

$this->app->singleton(Translator::class, DeepLTranslator::class);

Eight commands, no guesswork.

Translate a string, a lang file or a whole table — and price any of it before you spend a character.

translate:text

$ php artisan translate:text "Hello world" "Good evening" --to=it --to=fr
$ php artisan translate:text "Hello" --from=en --to=de --format=html --no-cache
$ php artisan translate:text "Hello" --to=it --dry-run   # price only

translate:lang

Reads lang/{from}/*.php and lang/{from}.json, translates only the lines the target does not have yet, and writes formatted PHP and JSON back. Placeholder protection is on, so :attribute and {count} survive. Nested arrays keep their structure and keys are sorted.

$ php artisan translate:lang --from=en --to=it --to=fr --dry-run
 INFO  [it] 214 lines would be translated (18 402 characters, USD 0.3680).
 INFO  [fr] 214 lines would be translated (18 402 characters, USD 0.3680).

$ php artisan translate:lang --from=en --to=it --group=auth --group=validation

translate:model

The rest

$ php artisan translate:languages --target=it --search=chin
$ php artisan translate:languages --offline        # no API call
$ php artisan translate:audit --to=it --threshold=0.7 --limit=200
$ php artisan translate:cost --file=storage/app/strings.txt --to=it
$ php artisan translate:stats --days=30
$ php artisan translate:cache-clear

No network, ever.

Two ways to test code that translates: the package's own fake, or Laravel's HTTP fake. Both are first-class, because underneath it really is just an HTTP client.

The fake

$fake = GoogleTranslate::fake();

$this->postJson('/webhooks/postmark', $payload)->assertOk();

$fake->assertTranslated('The recipient rejected the message')
     ->assertTranslatedTo('it')
     ->assertTranslatedCount(1);

Without stubs the fake returns "[it] the original text", which keeps failure messages readable — you can see at a glance what actually ran.

Stubbing

GoogleTranslate::fake([
    'Hello'   => 'Ciao',                                  // any target
    'Bye'     => ['it' => 'Ciao ciao', 'fr' => 'Au revoir'],  // per target
    'Dynamic' => fn ($text, $target) => "$target:$text",        // computed
])->detectAs('fr');

Assertions

The recording is open too: recorded(), recordedDetections() and translatedTexts() return collections you can assert on directly.

Asserting on the wire

Http::fake(['*translate/v2*' => Http::response([
    'data' => ['translations' => [['translatedText' => 'Ciao mondo']]],
])]);

GoogleTranslate::justTranslate('Hello world');

Http::assertSent(fn ($request) =>
    $request['target'] === 'it'
    && $request->hasHeader('X-goog-api-key')
);

Four jobs, worked through.

Each of these is a real shape the package was built for, written the way it would be written in an application.

A webhook that must never fail

The job's real work is storing a bounce record. A translation that fails should degrade, not take the record with it.

$message = Message::query()->updateOrCreate(['id' => $payload['MessageID']], [
    'body'    => $payload['Description'],
    'body_it' => GoogleTranslate::onFailUseSource()
        ->text($payload['Description']),
]);

Or push it past the response entirely, so the endpoint answers in milliseconds:

GoogleTranslate::deferred()->translate($description, fn ($t) => $message->update([
    'body_it' => $t->translatedText,
]));

Drafting a whole application's lang files

$ php artisan translate:lang --from=en --to=it --to=fr --to=de --dry-run
$ php artisan translate:lang --from=en --to=it --to=fr --to=de
$ php artisan translate:audit --to=it --threshold=0.65

An API resource in the caller's language

public function toArray($request): array
{
    return GoogleTranslate::to($request->user()->locale)->json([
        'id'    => $this->id,
        'title' => $this->title,
        'body'  => $this->body,
        'slug'  => $this->slug,
    ], only: ['title', 'body']);
}

A nightly backfill

Schedule::command('translate:model', [
    'App\Models\Message', '--to' => 'it', '--queue',
])->dailyAt('02:00');

The command only walks rows the whereTranslationMissing scope returns, so a quiet night queues nothing and costs nothing.

When it doesn't do what you meant.

Seven symptoms that cover almost everything, with the cause rather than a workaround.

MissingApiKeyException

GOOGLE_TRANSLATE_API_KEY is unset — or the config was cached before you set it. Run php artisan config:clear. The exception is thrown lazily on the first call, not at boot, so a missing key never breaks an unrelated deploy.

"API key not valid"

The key exists, but the Cloud Translation API is not enabled on that project, or a key restriction is blocking it. Check APIs & Services → Library first, then the key's restrictions.

UnsupportedLanguageException for a code Google supports

The bundled enum is behind. Set 'strict_languages' => false to pass the code straight through, and please open an issue so the enum catches up.

Placeholders still come back broken

The pattern is not one of the ten built-ins. Add it with preserving(['/your-pattern/']) or in placeholders.patterns. Anything that looks like /…/ is treated as a regex; anything else is quoted as a literal for you.

Translations don't change after a glossary edit

The old value is cached — the glossary is applied before the result is stored. php artisan translate:cache-clear, then try again.

The same string is translated twice

Check cache.enabled, then remember what the key is made of: source, target, format and text. text and html are separate entries, and so are two targets for one string.

Tests hit the network

Call GoogleTranslate::fake() or Http::fake(). Add Http::preventStrayRequests() to your TestCase and a forgotten fake becomes a failing test rather than a live call.

What you're relying on.

A small package with a narrow job, tested properly, and honest about what it sends where.

Requirements and support

• PHP 8.3 or newer
• Laravel 12 or 13, both covered by the test matrix
• A Google Cloud API key with the Cloud Translation API enabled
• No migrations, no tables, no published assets

What ships in the box

Running the suite

$ composer test        # Pest
$ composer analyse     # PHPStan level 6
$ composer format      # Pint

Those three commands are the contract. A pull request that keeps them green is a pull request that will be read quickly.

Privacy, plainly

Credits

Written and maintained by Gabriele Sbaiz. The 1.x line began as a fork of JoggApp/laravel-google-translate; 2.0 is a rewrite, and the debt is gladly acknowledged. Built on Laravel and spatie/laravel-package-tools.

Licence

MIT, and it will stay MIT. Nothing is paywalled, nothing phones home, and no feature is held back for sponsors — sponsorship buys maintenance time, not features.

Upgrading from 1.x.

2.0 is a rewrite, but the calls your application already makes keep working. Two things changed on purpose; everything else is shimmed.

The two real changes

Everything else keeps working

$result = GoogleTranslateToolkit::translate('Hello');

$result['translated_text'];        // as in 1.x
$result['source_language_code'];   // as in 1.x
$result->translatedText;          // new
(string) $result;               // new

Configuration

Republish to get the new sections. The 1.x keys are still read, so an un-republished config keeps working exactly as it did.

Drop the SDK

$ composer remove google/cloud-translate

2.0 talks to the v2 REST endpoint through Laravel's HTTP client. If nothing else in your application needs the Google SDK, removing it takes google/cloud-core, the auth layer and the protobuf shims with it.

What changed, and when.

Semantic versioning. Breaking changes only in a major, and each one explained in Upgrading.

2.0.0

A full rewrite for Laravel 12 and 13. The transport is now Laravel's HTTP client; google/cloud-translate is no longer required.

Added

• Fluent, immutable builder — from(), to(), asHtml(), withoutCache(), onFailUseSource(), preserving(), withoutGlossary(), deferred()
• Translation cache with partitioned batches, namespaced flushing and translate:cache-clear
• Multi-target fan-out through one bounded Http::pool()
• Placeholder protection — ten patterns masked and restored
• Glossary — protected terms and per-locale forced wording
• Round-trip QA with roundTrip() and translate:audit
• Cost control — estimate(), a daily character budget, translate:cost, translate:stats
• Eloquent — HasTranslations, the Translatable contract, whereTranslationMissing(), translate:model
• Queue support — TranslateAttributesJob, WarmTranslationCacheJob, warm()
• Sugar — @translateHtml, Str/Stringable/Collection macros, google_translate(), Rule::language(), the AsLanguage cast
• Testing — GoogleTranslate::fake() with six assertions
• Types — Language and TextFormat enums, typed exceptions, readonly data objects
• Eight artisan commands, replacing none (1.x had none)

Changed

• The API key travels in an X-goog-api-key header instead of the query string
• default_source may be null, which enables Google's auto-detection — 1.x always sent a source language
• Methods return typed objects that still array-access with the 1.x keys
• unlessLanguageIs() always returns a Translation

Fixed

• @translate($text, 'it') passed the target language into the source slot
• zh-TW could not be used as the configured default target — a ctype_lower check rejected it
• No timeout, retry or cache: every call hit the API and a single blip failed the caller
• Text returned by the source fallback was written to the cache as though it were a translation, so one outage served the source language for the whole cache lifetime

1.0.0

Initial release — a thin wrapper over google/cloud-translate with translation, batch translation, detection and a Blade directive.