Laravel Google Translate Laravel Package

Getting Started

1. Install and publish.

   composer require tanmuhittin/laravel-google-translate
   php artisan vendor:publish --provider="Tanmuhittin\LaravelGoogleTranslate\LaravelGoogleTranslateServiceProvider"
   

   This drops config/laravel_google_translate.php into your project. Everything the package does is driven by that file.

2. Pick a translator before you write any code. The config's api key selects the backend:

   • google — the stichoza/google-translate-php web endpoint. Free, zero setup, but unofficial and rate-limited.
   • Google Cloud Translation API — paid, stable, needs a service account / API key.
   • Yandex Translate API — needs yandex_api_key.
   • custom — your own class implementing ApiTranslatorContract.

   Put keys in .env, never in the committed config file. Then run php artisan config:clear — a cached config will silently ignore your new env vars and the command will fail with a confusing auth error.

3. Look first at your language tree, not the package. Open lang/ (Laravel 9+) or resources/lang/ and confirm your source locale, e.g. lang/en/. The package walks that directory and writes sibling locale folders. Run php artisan list to confirm the exact artisan signature in the installed version (translations:translate with interactive prompts in recent releases) — the README is thinner than the command options, and --help is authoritative.

4. First use case: bootstrap a brand-new locale. Commit your current lang/ first, create lang/de/ (empty is fine), then run the translate command against en → de. Diff the result immediately:

   php artisan translations:translate
   git diff --stat lang/de
   

   The first run is where you discover placeholder mangling, pluralization breakage, and which files are too large for your API quota — before it matters.

Implementation Patterns

Treat lang/en as canonical, everything else as generated output. The single most effective workflow: developers edit lang/en/*.php and lang/en.json only; the translate command regenerates other locales; a human reviewer (or a native-speaker PR) corrects the generated files. This keeps the "source of truth" unambiguous and makes re-running the translator idempotent.

Translate incrementally, not wholesale. On an established app, translate one file or one small directory per invocation. Big bang runs against validation.php or auth.php across ten locales will burn Cloud API quota and produce hundreds of unreviewable lines in one commit. Use one PR per locale, or per domain file, so the diff is reviewable.

Pivot through English for non-English pairs. If you need de → fr, translate en → fr rather than de → fr. Translation quality drops sharply on indirect pairs, and it halves the number of source-of-truth files you maintain.

Reserve Str::apiTranslate for runtime content, and cache it. Str::apiTranslate and Str::apiTranslateWithAttributes are the genuinely interesting part of this package: they let you translate dynamic strings (CMS copy, product names, notification bodies) at request time. But they are synchronous HTTP calls inside your request cycle. Day-to-day pattern:

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;

$localized = Cache::rememberForever(
    "tr:{$locale}:".md5($text),
    fn () => Str::apiTranslateWithAttributes($text, $source, $locale)
);

Always prefer apiTranslateWithAttributes over apiTranslate for anything user-facing — it preserves Laravel's :name-style attributes. Reach for plain apiTranslate only when you know the string has no substitutions. Also check the actual method signature in the source or via tinker before wiring it into a service; argument order differs from what you'd guess.

Wrap the API call in a domain service, not scattered across views. A thin TranslationService that owns caching, locale fallback, and exception handling means you can swap backends later without touching call sites.

Custom translator for anything serious. The custom_api_translator contract is the extension point worth learning. Implement ApiTranslatorContract against DeepL, OpenAI, or an in-house glossary service, and register it:

'custom_api_translator'       => env('CUSTOM_API_TRANSLATOR', MyTranslator::class),
'custom_api_translator_key'   => env('CUSTOM_API_TRANSLATOR_KEY'),

Then every command and every Str::apiTranslate* call routes through your class — including a glossary-based translator that protects brand terms, which the raw Google endpoint will happily mangle.

Schedule it in CI, but never auto-merge. A nightly job that translates only new keys and opens a PR is a good pattern; a job that force-pushes translated files to main is not. Machine translation needs a human gate, especially on marketing strings.

Gotchas and Tips

• The free google backend is scraping, not an API. It breaks without warning, throttles aggressively, and is unsuitable for production runtime calls via Str::apiTranslate. Fine for one-off bulk file translation behind a developer machine; use the Cloud API or a custom translator for anything in a request path.
• Overwrites are real. The command writes into existing target-language files. Without a clean git state you cannot tell what changed or recover a hand-corrected string. Always commit before running, and diff after.
• Placeholders and pluralization are the top failure mode. :attribute, :count, :min, and {name} survive only if you use apiTranslateWithAttributes. Laravel's pipe-based pluralization — {0} none|{1} one|[2,*] many — is often mangled into broken syntax, which produces runtime InvalidArgumentException from the translator. Grep every generated file for | and { after a run and fix those strings by hand; consider excluding validation.php from automated translation entirely.
• Array keys are not translated; values are. That's correct for Laravel (keys are lookup identifiers), but it surprises people who expected 'email' => 'E-mail' to become a translated key. It won't.
• Locale directory naming must match Laravel exactly. pt_BR, zh_CN, sr_Latn — a stray pt-BR folder is invisible to __() and will look like the translation silently failed.
• Config caching will bite you. After changing api, keys, or the custom translator class in .env, run php artisan config:clear. A stale cached config is the single most common "it's ignoring my settings" cause.
• Long HTML-heavy strings and multi-line messages translate poorly and sometimes return truncated output. Keep an eye on mail.php and notification templates; verify by rendering, not just by reading the PHP.
• Rate limits and partial writes. A quota error mid-run can leave one locale half-translated. Re-running is usually safe (values are overwritten, not appended), but verify the file list rather than assuming the run completed.
• Test with a single small file first. Pick one key in one file to validate backend, key, and locale routing before pointing it at the whole tree. Debugging is much easier when only one variable changed.
• Zero dependents and a thin README mean you should pin the version. composer require tanmuhittin/laravel-google-translate:^x.y and read the contract source when behavior is unclear — the code is small and is the real documentation. MIT license makes it safe to vendor or fork if the maintainer's roadmap diverges from yours.