Cloud Translate Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require google/cloud-translate
   

2. Authenticate (see Google Cloud PHP Auth Guide):
   • For Laravel, use the GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to your service account JSON key.
   • Example .env:

     GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
     

3. First translation (V3 client, recommended):

   use Google\Cloud\Translate\V3\TranslationServiceClient;
   
   $client = new TranslationServiceClient();
   $response = $client->translate('Hello world', ['targetLanguageCode' => 'es']);
   echo $response->getTranslations()[0]->getTranslatedText(); // "Hola mundo"
   

First Use Case: Dynamic User Content Translation

// In a Laravel controller
public function translateUserPost(Request $request)
{
    $client = new TranslationServiceClient();
    $text = $request->input('content');
    $targetLang = $request->input('target_lang', 'en');

    $response = $client->translate($text, [
        'targetLanguageCode' => $targetLang,
        'mimeType' => 'text/plain' // Optional: for HTML/rich text, use 'text/html'
    ]);

    return response()->json([
        'translated' => $response->getTranslations()[0]->getTranslatedText(),
        'detectedSource' => $response->getDetectedSourceLanguage()
    ]);
}

Key First Steps

1. Choose V3 over V2: The generated V3 client (TranslationServiceClient) supports gRPC (faster) and newer features like AdaptiveMT.
2. Cache responses: Use Laravel’s cache (e.g., Cache::remember) to avoid repeated API calls for identical text.
3. Handle errors: Wrap calls in try-catch for Google\ApiCore\ApiException (e.g., quota limits, invalid input).

Implementation Patterns

1. Service Layer Integration

Create a dedicated service class to abstract API calls:

// app/Services/TranslationService.php
namespace App\Services;

use Google\Cloud\Translate\V3\TranslationServiceClient;
use Google\ApiCore\ApiException;

class TranslationService
{
    protected TranslationServiceClient $client;

    public function __construct()
    {
        $this->client = new TranslationServiceClient();
    }

    public function translate(string $text, string $targetLang = 'en'): string
    {
        try {
            $response = $this->client->translate($text, [
                'targetLanguageCode' => $targetLang,
                'model' => 'base' // or 'adaptive' for AdaptiveMT
            ]);
            return $response->getTranslations()[0]->getTranslatedText();
        } catch (ApiException $e) {
            \Log::error("Translation failed: {$e->getMessage()}");
            throw new \RuntimeException("Translation service unavailable.");
        }
    }
}

Usage in Controller:

public function __invoke(Request $request)
{
    $translation = app(TranslationService::class)->translate(
        $request->text,
        $request->target_lang
    );
    // ...
}

2. Async Translation with Queues

For long-running translations (e.g., batch processing), use Laravel Queues:

// app/Jobs/TranslateTextJob.php
namespace App\Jobs;

use App\Services\TranslationService;
use Illuminate\Bus\Queueable;

class TranslateTextJob
{
    use Queueable;

    public function handle(TranslationService $service)
    {
        $text = 'Your text to translate';
        $translation = $service->translate($text, 'fr');
        // Store result in DB or send notification
    }
}

Dispatch:

TranslateTextJob::dispatch()->onQueue('translations');

3. Batch Translation

For multiple texts (e.g., CSV imports):

public function batchTranslate(array $texts, string $targetLang): array
{
    $requests = [];
    foreach ($texts as $text) {
        $requests[] = (new TranslateTextRequest())
            ->setContents($text)
            ->setMimeType('text/plain');
    }

    $response = $this->client->batchTranslate([
        'parent' => 'projects/YOUR_PROJECT_ID/locations/global',
        'requests' => $requests,
        'targetLanguageCode' => $targetLang
    ]);

    return array_map(
        fn($t) => $t->getTranslatedText(),
        $response->getTranslations()
    );
}

4. Adaptive Machine Translation (AdaptiveMT)

For domain-specific translations (e.g., legal, medical):

// Train a custom model first (via Google Cloud Console)
// Then use it:
$response = $client->translate($text, [
    'targetLanguageCode' => 'de',
    'model' => 'projects/YOUR_PROJECT_ID/locations/us/glossaries/YOUR_GLOSSARY_ID'
]);

5. Language Detection

$response = $client->detectLanguage('Bonjour le monde');
echo $response->getLanguageCodes()[0]; // "fr"

6. Document Translation (PDF/DOCX)

use Google\Cloud\Translate\V3\TranslateDocumentRequest;

$gcsUri = 'gs://your-bucket/document.pdf';
$response = $client->translateDocument((new TranslateDocumentRequest())
    ->setParent('projects/YOUR_PROJECT_ID/locations/global')
    ->setGcsSource(['inputUri' => $gcsUri])
    ->setMimeType('application/pdf')
    ->setTargetLanguageCode('en')
);

foreach ($response->getTranslations() as $translation) {
    echo $translation->getTranslatedText();
}

7. Integration with Laravel Localization

Extend Laravel’s AppServiceProvider:

public function boot()
{
    view()->composer('*', function ($view) {
        $view->with('translations', collect([
            'greeting' => app(TranslationService::class)->translate(
                'Hello',
                app()->getLocale()
            ),
        ]));
    });
}

8. Testing

Use mocks for unit tests (e.g., with Mockery):

public function test_translation_service()
{
    $mockClient = Mockery::mock(TranslationServiceClient::class);
    $mockClient->shouldReceive('translate')
        ->once()
        ->andReturn((new TranslateTextResponse())
            ->setTranslations([(new TranslatedText())
                ->setTranslatedText('Hola')])
        );

    $service = new TranslationService($mockClient);
    $this->assertEquals('Hola', $service->translate('Hello', 'es'));
}

Gotchas and Tips

Authentication Pitfalls

1. Service Account Permissions:

   • Ensure your service account has the Cloud Translation User (roles/cloudtranslate.user) role.
   • Gotcha: Missing permissions cause PERMISSION_DENIED errors without clear logs. Use:

     gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
         --member="serviceAccount:YOUR_SERVICE_ACCOUNT@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
         --role="roles/cloudtranslate.user"
     

2. Environment Variables:

   • Laravel’s .env must load the JSON key before the client initializes. Use:

     putenv('GOOGLE_APPLICATION_CREDENTIALS=' . storage_path('app/google-credentials.json'));
     

   • Tip: For Laravel Forge/Laravel Vapor, store the key in environment variables (not files).

3. Local Development:

   • Use Application Default Credentials with:

     gcloud auth application-default login
     

API Quotas and Costs

1. Free Tier:

   • 500,000 characters/month free (shared across all Google Cloud services).
   • Tip: Monitor usage in Google Cloud Console.

2. Quota Limits:

   • Default: 1,000 requests/minute. Exceeding this throws RESOURCE_EXHAUSTED.
   • Solution: Implement exponential backoff:

     use Google\ApiCore\RetrySettings;
     
     $retrySettings = new RetrySettings();
     $retrySettings->setMaxAttempts(3);
     $retrySettings->setInitialRetryDelay(0.1);
     $retrySettings->setRetryDelayMultiplier(2);
     $retrySettings->setMaxRetryDelay(10);
     
     $client = new TranslationServiceClient(['retrySettings' => $retrySettings]);
     

3. Pricing:

   • $0.0004 per 1,000 characters (after free tier).