README

A modern, production-ready, and well-documented PHP translation package with advanced language negotiation, URL localization, route translation, and comprehensive Laravel integration. Now fully compatible with Laravel 12!

✨ Features

• 🌍 Automatic Language Detection - Intelligent locale detection from Accept-Language headers
• 🔗 URL-based Locale Switching - Clean, SEO-friendly localized URLs
• 🛣️ Route Translation - Translate route patterns and parameters
• ⚡ Performance Optimized - Built-in caching and optimization for Laravel 12
• 🔧 Middleware Integration - Seamless Laravel 12 middleware support
• 🎯 Type Safe - Full PHP 8.1+ type declarations and strict types
• 📱 Multi-directional Support - LTR and RTL language support
• 🍪 Session & Cookie Support - Remember user language preferences
• 🧪 Comprehensive Testing - Full test suite included
• 📚 Rich Documentation - Extensive documentation and examples
• 🚀 Laravel 12 Ready - Fully compatible with the latest Laravel version

🚀 Installation

Install the package via Composer:

composer require litepie/trans

Laravel Auto-Discovery

The package will automatically register its service provider and aliases.

Manual Registration (if needed)

Add the service provider to your config/app.php:

'providers' => [
    // Other providers...
    Litepie\Trans\TransServiceProvider::class,
],

Publish Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Litepie\Trans\TransServiceProvider" --tag="trans-config"

⚙️ Configuration

The configuration file config/trans.php provides extensive customization options:

<?php

return [
    // Supported locales with metadata
    'supportedLocales' => [
        'en' => [
            'name' => 'English',
            'script' => 'Latn',
            'native' => 'English',
            'regional' => 'en_US',
            'dir' => 'ltr',
        ],
        'es' => [
            'name' => 'Spanish',
            'script' => 'Latn', 
            'native' => 'Español',
            'regional' => 'es_ES',
            'dir' => 'ltr',
        ],
        // More locales...
    ],

    // Use Accept-Language header for negotiation
    'useAcceptLanguageHeader' => true,

    // Hide default locale in URLs (/en/page becomes /page)
    'hideDefaultLocaleInURL' => false,

    // Auto-detect and redirect to user's preferred locale
    'autoDetectLocale' => true,

    // Additional configuration options...
];

🎯 Basic Usage

Setting Up Middleware

Add the localization middleware to your routes:

// In routes/web.php
Route::group(['middleware' => 'localization'], function () {
    Route::get('/', 'HomeController@index');
    Route::get('/about', 'AboutController@index');
    // Your localized routes...
});

Using the Trans Service

<?php

use Litepie\Trans\Trans;

class HomeController extends Controller
{
    protected Trans $trans;

    public function __construct(Trans $trans)
    {
        $this->trans = $trans;
    }

    public function index()
    {
        // Get current locale
        $currentLocale = $this->trans->getCurrentLocale(); // 'en'

        // Get localized URL for different locale
        $spanishUrl = $this->trans->getLocalizedURL('es'); 

        // Check if multilingual
        $isMultilingual = $this->trans->isMultilingual(); // true/false

        // Get all supported locales
        $locales = $this->trans->getSupportedLocales();

        return view('home', compact('currentLocale', 'spanishUrl', 'locales'));
    }
}

Language Switcher in Blade Templates

Create a language switcher component:

{{-- resources/views/components/language-switcher.blade.php --}}
@inject('trans', 'Litepie\Trans\Trans')

<div class="language-switcher">
    <div class="dropdown">
        <button class="dropdown-toggle">
            {{ $trans->getCurrentLocaleNative() }}
            <span class="flag flag-{{ $trans->getCurrentLocale() }}"></span>
        </button>
        
        <div class="dropdown-menu">
            @foreach($trans->getSupportedLocales() as $code => $locale)
                @if($code !== $trans->getCurrentLocale())
                    <a href="{{ $trans->getLocalizedURL($code) }}" 
                       class="dropdown-item">
                        <span class="flag flag-{{ $code }}"></span>
                        {{ $locale['native'] }}
                    </a>
                @endif
            @endforeach
        </div>
    </div>
</div>

🌐 Advanced Features

Route Translation

Define translated routes in your language files:

// resources/lang/en/routes.php
return [
    'about' => 'about',
    'contact' => 'contact',
    'products' => 'products',
];

// resources/lang/es/routes.php  
return [
    'about' => 'acerca-de',
    'contact' => 'contacto', 
    'products' => 'productos',
];

Register translated routes:

Route::group(['middleware' => 'localization'], function () {
    Route::get(trans('routes.about'), 'AboutController@index')->name('about');
    Route::get(trans('routes.contact'), 'ContactController@index')->name('contact');
});

Custom Language Negotiation

use Litepie\Trans\LanguageNegotiator;

$negotiator = new LanguageNegotiator(
    'en', // default locale
    ['en' => [...], 'es' => [...]], // supported locales
    $request
);

$bestLocale = $negotiator->negotiateLanguage();

Locale Detection Priority

The package detects locale in this order:

1. URL segment - /es/page (highest priority)
2. Session - Stored user preference
3. Cookie - Persistent preference
4. Accept-Language header - Browser preference
5. Default locale - Fallback (lowest priority)

🔧 Middleware Options

LocalizationMiddleware

Automatically handles locale detection and URL redirection:

Route::group(['middleware' => 'localization'], function () {
    // Your routes
});

Custom Middleware Usage

public function handle($request, Closure $next)
{
    // Custom logic before localization
    
    $response = $next($request);
    
    // Custom logic after localization
    
    return $response;
}

📊 API Reference

Trans Class Methods

Locale Management

// Set current locale
$trans->setLocale('es'); // Returns: 'es'

// Get current locale  
$trans->getCurrentLocale(); // Returns: 'en'

// Get default locale
$trans->getDefaultLocale(); // Returns: 'en'

// Check if locale is supported
$trans->checkLocaleInSupportedLocales('fr'); // Returns: true/false

Locale Information

// Get locale display name
$trans->getCurrentLocaleName(); // Returns: 'English'

// Get locale native name  
$trans->getCurrentLocaleNative(); // Returns: 'English'

// Get text direction
$trans->getCurrentLocaleDirection(); // Returns: 'ltr' or 'rtl'

// Get locale script
$trans->getCurrentLocaleScript(); // Returns: 'Latn'

// Get regional locale
$trans->getCurrentLocaleRegional(); // Returns: 'en_US'

URL Generation

// Generate localized URL
$trans->getLocalizedURL('es', '/products'); 
// Returns: 'https://site.com/es/productos'

// Generate non-localized URL
$trans->getNonLocalizedURL('/es/productos');
// Returns: 'https://site.com/productos'

// Get URL from route name
$trans->getURLFromRouteNameTranslated('es', 'products');

Utility Methods

// Check if application is multilingual
$trans->isMultilingual(); // Returns: true/false

// Get all supported locales
$trans->getSupportedLocales(); // Returns: array

// Get supported locale keys
$trans->getSupportedLanguagesKeys(); // Returns: ['en', 'es', 'fr']

LanguageNegotiator Class

// Negotiate best language
$negotiator->negotiateLanguage(); // Returns: 'es'

// Get supported languages  
$negotiator->getSupportedLanguages(); // Returns: array

// Check if language is supported
$negotiator->isLanguageSupported('fr'); // Returns: true/false

// Get best match for language
$negotiator->getBestMatch('en-US'); // Returns: 'en'

🧪 Testing

Run the test suite:

# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run specific test
./vendor/bin/phpunit tests/Unit/TransTest.php

Example Test

<?php

use Litepie\Trans\Trans;
use Litepie\Trans\LanguageNegotiator;

class TransTest extends TestCase
{
    public function test_can_set_and_get_locale()
    {
        $trans = $this->app->make(Trans::class);
        
        $result = $trans->setLocale('es');
        
        $this->assertEquals('es', $result);
        $this->assertEquals('es', $trans->getCurrentLocale());
    }

    public function test_can_generate_localized_url()
    {
        $trans = $this->app->make(Trans::class);
        
        $url = $trans->getLocalizedURL('es', '/products');
        
        $this->assertStringContains('/es/', $url);
    }
}

🔒 Security Considerations

• ✅ Input Validation - All locale inputs are validated against supported locales
• ✅ XSS Protection - Output is properly escaped in Blade components
• ✅ CSRF Protection - Compatible with Laravel's CSRF middleware
• ✅ SQL Injection - No direct database queries, uses Laravel's query builder

🚀 Performance Tips

1. Enable Route Caching:

   'cacheRouteTranslations' => true,
   'routeTranslationCacheTTL' => 60, // minutes

2. Use Laravel's Route Caching:

   php artisan route:cache

3. Optimize Config Loading:

   php artisan config:cache

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Development Setup

# Clone the repository
git clone https://github.com/litepie/trans.git

# Install dependencies
composer install

# Run tests
composer test

# Check code style
composer cs-check

# Fix code style
composer cs-fix

📝 Changelog

Please see CHANGELOG.md for recent changes.

🛡️ Security

If you discover any security-related issues, please email security@litepie.com instead of using the issue tracker.

📄 License

This package is open-sourced software licensed under the MIT license.

🙏 Credits

• Original Lavalite Team - For the foundation
• Laravel Community - For the amazing framework
• Contributors - All the people who have contributed to this project

🔗 Links

• Documentation
• Issue Tracker
• Source Code
• Packagist

Made with ❤️ by the Lavalite Team