README

A comprehensive Laravel package for multi-service translation with support for Google Translate, Azure Translator, DeepL, OpenAI, Yandex Translate, and Amazon Translate.

Features

Multiple Translation Services: Supports 6 major translation APIs
Unified Interface: Single API for all services
Spatie Translatable Integration: Works seamlessly with spatie/laravel-translatable
Plug-and-Play: Easy service switching via configuration
Batch Translation: Translate multiple texts efficiently
Model Translation: Auto-translate model fields
Error Handling: Robust error handling with standardized responses
Caching Support: Reduce API calls and costs
Fallback Support: Automatic fallback to alternative services

Installation

1. Add to composer.json

Since this is a local package, add it to your main project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/translation-services"
        }
    ],
    "require": {
        "fastnet/translation-services": "*"
    }
}

2. Install the package

composer update fastnet/translation-services

3. Publish configuration

php artisan vendor:publish --tag=translation-services-config

4. Configure services

Edit config/translation-services.php or add to your .env:

# Default service
TRANSLATION_SERVICE=google

# Google Translate
GOOGLE_TRANSLATE_ENABLED=true
GOOGLE_TRANSLATE_API_KEY=your-api-key

# DeepL
DEEPL_ENABLED=true
DEEPL_API_KEY=your-api-key
DEEPL_PRO=false

# Azure Translator
AZURE_TRANSLATE_ENABLED=true
AZURE_TRANSLATE_API_KEY=your-api-key
AZURE_TRANSLATE_REGION=global

# OpenAI
OPENAI_TRANSLATE_ENABLED=true
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-3.5-turbo

# Yandex Translate
YANDEX_TRANSLATE_ENABLED=true
YANDEX_TRANSLATE_API_KEY=your-api-key
YANDEX_FOLDER_ID=your-folder-id

# Amazon Translate
AMAZON_TRANSLATE_ENABLED=true
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1

Usage

Basic Translation

use Fastnet\TranslationServices\Facades\Translator;

// Translate text
$result = Translator::translate('Hello World', 'ar');

if ($result['success']) {
    echo $result['translated_text']; // مرحبا بالعالم
}

Using Specific Service

// Use Google Translate
$result = Translator::useService('google')
    ->translate('Hello World', 'es');

// Use DeepL
$result = Translator::useService('deepl')
    ->translate('Hello World', 'de');

// Use OpenAI
$result = Translator::useService('openai')
    ->translate('Hello World', 'fr');

Batch Translation

$texts = [
    'Hello World',
    'Good Morning',
    'Thank You'
];

$results = Translator::translateBatch($texts, 'ar');

foreach ($results as $result) {
    if ($result['success']) {
        echo $result['translated_text'] . "\n";
    }
}

Model Translation (Spatie Translatable)

use Spatie\Translatable\HasTranslations;

class Product extends Model
{
    use HasTranslations;

    public array $translatable = ['name', 'description'];
}

// Translate model fields
$product = Product::find(1);

$results = Translator::translateModel(
    model: $product,
    fields: ['name', 'description'],
    targetLanguage: 'ar',
    sourceLanguage: 'en',
    save: true
);

// Check results
foreach ($results as $field => $result) {
    if ($result['success']) {
        echo "{$field}: {$result['translated_text']}\n";
    }
}

Advanced Model Translation

// Translate to multiple languages
$product = Product::find(1);
$languages = ['ar', 'es', 'fr', 'de'];

foreach ($languages as $lang) {
    Translator::translateModel(
        $product,
        ['name', 'description'],
        $lang,
        'en'
    );
}

// Now you can use:
$product->getTranslation('name', 'ar');
$product->getTranslation('description', 'es');

Using Without Facade

use Fastnet\TranslationServices\TranslationManager;

$translator = new TranslationManager();

$result = $translator->translate('Hello World', 'ar');

Dependency Injection

use Fastnet\TranslationServices\TranslationManager;

class TranslationService
{
    public function __construct(
        private TranslationManager $translator
    ) {}

    public function translateProduct(Product $product, string $language)
    {
        return $this->translator->translateModel(
            $product,
            ['name', 'description'],
            $language
        );
    }
}

Response Format

All translation methods return a standardized response:

[
    'success' => true,
    'translated_text' => 'مرحبا بالعالم',
    'source_language' => 'en',
    'target_language' => 'ar',
    'service' => 'google',
    'metadata' => [
        'model' => 'nmt',
        'confidence' => 0.99
    ],
    'error' => null
]

Error Response

[
    'success' => false,
    'translated_text' => null,
    'source_language' => 'en',
    'target_language' => 'ar',
    'service' => 'google',
    'metadata' => [],
    'error' => [
        'message' => 'API key invalid',
        'code' => 401
    ]
]

Check Available Services

$services = Translator::getAvailableServices();

foreach ($services as $service) {
    echo "{$service['display_name']}: " .
         ($service['configured'] ? 'Ready' : 'Not configured') . "\n";
}

Check Specific Service

if (Translator::hasService('deepl')) {
    $result = Translator::useService('deepl')
        ->translate('Hello', 'de');
}

Real-World Example

Translating Product Catalog

use App\Models\Product;
use Fastnet\TranslationServices\Facades\Translator;

class ProductTranslationService
{
    public function translateAllProducts(string $targetLanguage)
    {
        $products = Product::all();
        $results = [];

        foreach ($products as $product) {
            try {
                $result = Translator::useService('deepl')
                    ->translateModel(
                        $product,
                        ['name', 'description', 'features'],
                        $targetLanguage,
                        'en',
                        true
                    );

                $results[] = [
                    'product_id' => $product->id,
                    'success' => !empty(array_filter($result, fn($r) => $r['success'])),
                    'details' => $result
                ];
            } catch (\Exception $e) {
                $results[] = [
                    'product_id' => $product->id,
                    'success' => false,
                    'error' => $e->getMessage()
                ];
            }
        }

        return $results;
    }
}

Command to Translate Models

use Illuminate\Console\Command;
use Fastnet\TranslationServices\Facades\Translator;

class TranslateProductsCommand extends Command
{
    protected $signature = 'products:translate {language}';
    protected $description = 'Translate all products to specified language';

    public function handle()
    {
        $language = $this->argument('language');
        $products = Product::all();

        $this->withProgressBar($products, function ($product) use ($language) {
            Translator::translateModel(
                $product,
                ['name', 'description'],
                $language,
                'en'
            );
        });

        $this->info("\nTranslation completed!");
    }
}

Service-Specific Features

Google Translate

Auto language detection
Wide language support
Fast and reliable

DeepL

High-quality translations
Free and Pro tiers
Excellent for European languages

Azure Translator

Microsoft's translation service
Regional deployment
High accuracy

OpenAI (ChatGPT)

Context-aware translations
Natural language understanding
Flexible model selection (GPT-3.5/GPT-4)

Yandex Translate

Good for Russian and Eastern European languages
Cloud-based service

Amazon Translate

AWS integration
Custom terminology support
Scalable

Language Codes

Common language codes supported by most services:

en - English
ar - Arabic
es - Spanish
fr - French
de - German
it - Italian
pt - Portuguese
ru - Russian
zh - Chinese
ja - Japanese
ko - Korean
hi - Hindi
ur - Urdu

Error Handling

$result = Translator::translate('Hello', 'ar');

if (!$result['success']) {
    Log::error('Translation failed', [
        'service' => $result['service'],
        'error' => $result['error']['message']
    ]);

    // Use fallback text
    $translatedText = $originalText;
} else {
    $translatedText = $result['translated_text'];
}

Testing

The package includes robust error handling and logging. To test:

// Test service configuration
$service = Translator::driver('google');
if ($service->isConfigured()) {
    echo "Service is configured correctly\n";
}

// Test translation
$result = Translator::translate('Test', 'ar');
dd($result);

Cost Optimization

Enable Caching: Cache translations to avoid repeated API calls
Batch Translations: Use translateBatch() when translating multiple texts
Choose Right Service: Different services have different pricing models
Use Free Tiers: DeepL offers free tier, OpenAI has lower costs for GPT-3.5

Extending the Package

Adding a New Service

Create service class in src/Services/
Implement TranslationServiceInterface
Extend BaseTranslationService
Add to TranslationManager::driver() method
Add configuration in config/translation-services.php

License

MIT License

Support

For issues and feature requests, please contact the development team.

rkwebsolution / translation-services

Maintainers

Details