README

A comprehensive, modern Laravel package for managing multilingual applications with database-driven translations, automatic locale detection, and a beautiful admin interface. Built for Laravel 10+ with full support for the latest language directory structure.

✨ Features

• 🌐 12+ Languages: Pre-configured support for major world languages
• 🎯 Smart Locale Detection: Browser, URL, session, and cookie-based detection
• 📁 Modern Laravel Compatibility: Laravel 10/11 lang/ directory structure
• 🗂️ Dual Format Support: Both PHP arrays and JSON translations
• 🗃️ Database-Driven Translations: Store translations in database with file fallback
• 🎛️ Professional Admin Interface: Beautiful Tailwind CSS interface
• ⚡ Performance Optimized: Built-in caching and file-based translations
• 🔧 Artisan Commands: CLI tools for import/export and management
• 🛣️ SEO Friendly: Automatic hreflang tags and localized URLs
• 📱 API Support: RESTful API with intelligent locale detection
• 🔄 Hot Reloading: Automatic file export on database changes
• 🔀 Flexible Loading: Database-first with automatic file fallback

📋 Requirements

• PHP: 8.2 or higher
• Laravel: 10.0 or higher
• Extensions: mbstring, json

🚀 Quick Installation

1. Install via Composer

composer require jawabapp/localization

2. Publish Configuration

# Publish config file
php artisan vendor:publish --tag=localization-config

# Publish and run migrations
php artisan vendor:publish --tag=localization-migrations
php artisan migrate

3. Configure Middleware

For Laravel 11+, add the middleware to your bootstrap/app.php:

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        // Register localization middleware
        $middleware->alias([
            'localization' => \Jawabapp\Localization\Http\Middleware\Web\Localization::class,
            'localization.web' => \Jawabapp\Localization\Http\Middleware\Web\Localization::class,
            'localization.api' => \Jawabapp\Localization\Http\Middleware\Api\Localization::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

For Laravel 10 and earlier, add the middleware to your app/Http/Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \Jawabapp\Localization\Http\Middleware\Web\Localization::class,
    ],

    'api' => [
        // ... other middleware
        \Jawabapp\Localization\Http\Middleware\Api\Localization::class,
    ],
];

4. Setup Route Prefixes

Update your App\Providers\RouteServiceProvider.php:

use Jawabapp\Localization\Libraries\Localization;

public function boot(): void
{
    // Web routes with locale prefix
    Route::prefix(Localization::routePrefix())
        ->middleware('web')
        ->group(base_path('routes/web.php'));
}

5. Access the Admin Interface

Visit /localization in your browser to manage translations!

🗃️ Database-Driven Translations

The package automatically uses database-driven translations with file fallback. This means:

• ✅ Primary: Translations are loaded from the database first
• ✅ Fallback: If database is unavailable, files are used automatically
• ✅ Performance: Results are cached for optimal performance
• ✅ Flexibility: You can disable database translations if needed

Configuration

Control database translations in config/localization.php:

'database_translations' => [
    'enabled' => true, // Enable database translations
    'fallback_to_files' => true, // Fallback to file translations if database fails
],

How It Works

1. Translation Request: When you call __('messages.welcome') or trans('auth.failed')
2. Database Check: Package checks the database for the translation first
3. File Fallback: If not found in database, loads from lang/ files
4. Caching: Results are cached to avoid repeated database queries
5. Admin Interface: Manage all translations through the web interface at /localization

Automatic Setup

The database translation system is automatically configured when you install the package:

• 🔧 Auto-Discovery: Laravel automatically registers the TranslationServiceProvider
• 🔄 Seamless Integration: Replaces Laravel's default translator with our enhanced version
• 📊 No Code Changes: Your existing __() and trans() calls work unchanged
• 🛡️ Safe Fallback: If database fails, translations load from files automatically

Disabling Database Translations

To use only file-based translations, set in your config:

'database_translations' => [
    'enabled' => false, // Disable database translations - use files only
],

⚙️ Configuration

The main configuration file is published to config/localization.php:

<?php

return [
    // Supported locales
    'supported_locales' => ['en', 'ar', 'es', 'fr', 'de'],

    // Locale detection
    'detect_browser_locale' => true,
    'store_in_session' => true,
    'store_in_cookie' => true,

    // URL configuration
    'url' => [
        'hide_default' => true, // Hide default locale in URLs
        'force_locale_in_url' => false,
    ],

    // Cache settings
    'cache' => [
        'enabled' => true,
        'duration' => 60 * 24, // 24 hours
    ],

    // Translation groups
    'translation_groups' => [
        'auth', 'validation', 'general', 'messages'
    ],
];

Available Locales

The package comes pre-configured with these locales:

📖 Usage Guide

Basic Translation Management

Use Laravel's built-in translation functions:

// In controllers or views
echo __('messages.welcome');
echo trans('auth.failed');
echo trans_choice('messages.items', 5);

// With parameters
echo __('messages.hello', ['name' => 'John']);

Dynamic Locale Switching

use Jawabapp\Localization\Libraries\Localization;

// Set locale programmatically
Localization::setLocale('fr');

// Get current locale
$locale = app()->getLocale();

// Get all supported locales
$locales = Localization::getSupportedLocales();

// Get locale native name
$name = Localization::getLocaleName('ar'); // Returns: العربية

Working with Localized Routes

Create routes that automatically work with all locales:

Route::localized(function ($locale) {
    Route::get('/', [HomeController::class, 'index'])->name('home');
    Route::get('/about', [AboutController::class, 'index'])->name('about');
    Route::get('/products', [ProductController::class, 'index'])->name('products');
});

Generate localized URLs:

// Current locale URL
$url = route('products');

// Specific locale URL
$url = Route::localizedUrl('products', 'fr');

// Get all locale URLs for hreflang tags
$alternateUrls = Localization::getAlternateUrls();

Model Integration

For models with translatable fields, use the _key suffix:

class Post extends Model
{
    protected $fillable = ['title_key', 'content_key', 'slug'];

    // Accessors for translated content
    public function getTitleAttribute()
    {
        return $this->title_key ? __($this->title_key) : '';
    }

    public function getContentAttribute()
    {
        return $this->content_key ? __($this->content_key) : '';
    }
}

// Usage
$post = Post::create([
    'title_key' => 'My Blog Post Title',
    'content_key' => 'This is the blog post content...',
    'slug' => 'my-blog-post'
]);

🎛️ Admin Interface

Access the admin interface at /localization to:

Translation Management

• ✅ View all translations by language and group
• ✅ Add, edit, and delete translations
• ✅ Search and filter translations
• ✅ Bulk operations (delete, export)
• ✅ Visual translation status indicators

Import/Export Tools

• ✅ Export translations to PHP/JSON files
• ✅ Import from existing language files
• ✅ Sync translations between locales
• ✅ Translation statistics and completion rates

Features

• 📱 Responsive Design: Works perfectly on mobile and desktop
• 🎨 Modern UI: Beautiful Tailwind CSS interface
• ⚡ Real-time Updates: Live search and filtering
• 🔄 Batch Operations: Handle multiple translations at once

🔧 Artisan Commands

The package includes powerful CLI commands:

Export Translations

# Export all translations
php artisan localization:export

# Export specific locale
php artisan localization:export --locale=fr

# Export specific group
php artisan localization:export --locale=en --group=auth

# Export only JSON format
php artisan localization:export --format=json

Import Translations

# Import all translations from files
php artisan localization:import

# Import specific locale
php artisan localization:import --locale=fr

# Overwrite existing translations
php artisan localization:import --overwrite

Sync Between Locales

# Sync missing translations from English to French
php artisan localization:sync --from=en --to=fr --missing-only

# Copy all translations (overwrite existing)
php artisan localization:sync --from=en --to=de --overwrite

Cache Management

# Clear translation cache
php artisan localization:clear-cache

# Clear cache for specific locale
php artisan localization:clear-cache --locale=fr

🌐 API Usage

The package provides full API support with intelligent locale detection:

Request Headers

# Custom headers
curl -H "X-Localization: fr" /api/endpoint
curl -H "X-Locale: es" /api/endpoint

# Standard Accept-Language header
curl -H "Accept-Language: fr,en;q=0.8" /api/endpoint

Query Parameters

curl /api/endpoint?locale=fr

Response Headers

The API middleware automatically adds:

• Content-Language: fr header to responses
• Proper locale detection from multiple sources

🗂️ File Structure

The package supports Laravel's modern language directory structure:

lang/
├── en/
│   ├── auth.php
│   ├── validation.php
│   └── messages.php
├── fr/
│   ├── auth.php
│   └── validation.php
├── ar/
│   └── messages.php
├── en.json
├── fr.json
└── ar.json

File Types

• PHP Files (lang/{locale}/group.php): Structured translations with nested arrays
• JSON Files (lang/{locale}.json): Simple key-value translations

🔍 SEO Features

Automatic Hreflang Tags

Add to your layout:

@foreach(Localization::getAlternateUrls() as $locale => $url)
    <link rel="alternate" hreflang="{{ $locale }}" href="{{ $url }}" />
@endforeach

Localized URLs

// Generates: /en/products or /products (if default)
Route::get('/products', [ProductController::class, 'index'])->name('products');

⚡ Performance Optimization

Caching

Translations are automatically cached:

// Cache keys:
// localization.{locale} - All translations for locale
// localization.{locale}.{group} - Specific group translations

Static File Export

Export to static files for optimal performance:

php artisan localization:export

Static files load faster than database queries and are automatically cached by Laravel.

🔧 Advanced Configuration

Custom Database Connection

'database' => [
    'connection' => 'translations_db',
    'table' => 'app_translations',
],

Custom Translation Groups

'translation_groups' => [
    'auth', 'validation', 'emails',
    'custom_module', 'product_catalog'
],

Middleware Configuration

'routes' => [
    'enabled' => true,
    'prefix' => 'admin/localization', // Custom admin path
    'middleware' => ['web', 'auth', 'admin'],
],

📚 Examples

Complete Laravel Application Setup

1. Install and Configure:

composer require jawabapp/localization
php artisan vendor:publish --tag=localization-config
php artisan migrate

1. Create Localized Routes:

// routes/web.php
Route::localized(function ($locale) {
    Route::get('/', function () {
        return view('welcome');
    })->name('home');

    Route::get('/products', function () {
        return view('products.index');
    })->name('products');

    Route::get('/contact', function () {
        return view('contact');
    })->name('contact');
});

1. Add Language Switcher:

<!-- resources/views/layouts/app.blade.php -->
<div class="language-switcher">
    @foreach(Localization::getSupportedLocales() as $locale)
        <a href="{{ Route::localizedUrl(Route::currentRouteName(), $locale) }}"
           class="{{ app()->getLocale() === $locale ? 'active' : '' }}">
            {{ Localization::getLocaleName($locale) }}
        </a>
    @endforeach
</div>

1. Use Translations in Views:

<!-- resources/views/welcome.blade.php -->
<h1>{{ __('messages.welcome') }}</h1>
<p>{{ __('messages.description', ['app' => config('app.name')]) }}</p>

API Integration

// app/Http/Controllers/Api/ProductController.php
class ProductController extends Controller
{
    public function index(Request $request)
    {
        // Locale is automatically set by middleware
        $locale = app()->getLocale();

        $products = Product::select([
            'id', 'name_key', 'description_key', 'price'
        ])->get()->map(function ($product) {
            return [
                'id' => $product->id,
                'name' => __($product->name_key),
                'description' => __($product->description_key),
                'price' => $product->price,
            ];
        });

        return response()->json($products);
    }
}

🐛 Troubleshooting

Common Issues

1. Translations not loading

# Clear cache and regenerate
php artisan localization:clear-cache
php artisan localization:export

2. Middleware not working (Laravel 11)

// Ensure middleware is registered in bootstrap/app.php
$middleware->alias([
    'localization' => \Jawabapp\Localization\Http\Middleware\Web\Localization::class,
]);

2b. Middleware not working (Laravel 10 and earlier)

// Ensure middleware is registered in Kernel.php
\Jawabapp\Localization\Http\Middleware\Web\Localization::class,

3. Routes not found

// Make sure RouteServiceProvider is configured
Route::prefix(Localization::routePrefix())
    ->middleware('web')
    ->group(base_path('routes/web.php'));

4. Admin interface 404

# Check if routes are enabled
'routes' => ['enabled' => true]

5. "Call to a member function total() on array" error

# This error occurs when the layout expects paginated data but receives an array
# The fix is included in the updated controller - no action needed for users

6. "Class Jawabapp\Localization\Libraries\Localization not found" error

# This error occurs when trying to update translations
# The fix is included in the updated controller - no action needed for users

7. Export functionality not working

# If Artisan commands don't work from web interface, try from command line:
php artisan localization:export

# The web interface now includes direct export functionality as fallback

8. "SQLSTATE[23000]: Integrity constraint violation: 19 NOT NULL constraint failed: translations.key"

# This occurs when translation key parsing fails
# Ensure your translations have proper namespace, group, and key structure
# The updated controller handles this automatically

Debug Mode

Enable debug logging:

'fallback' => [
    'log_missing' => env('APP_DEBUG', false),
],

Performance Issues

# Enable caching
php artisan config:cache

# Export translations to static files
php artisan localization:export

🔄 Upgrading from v1.x

The package uses a new database schema:

1. Backup translations:

php artisan localization:export

1. Run migration:

php artisan migrate

1. Verify data: The migration automatically converts language_code → locale and extracts groups from keys.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

# Clone repository
git clone https://github.com/jawabapp/localization
cd localization

# Install dependencies
composer install
npm install

# Run tests
composer test

🔐 Security

If you discover security vulnerabilities, please email i.qanah@gmail.com instead of using the issue tracker.

📜 License

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

👨‍💻 Credits

• Ibraheem Qanah - Creator & Maintainer
• All Contributors - Thank you!

🌟 Support

• ⭐ Star this repo if it helped you!
• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation

Made with ❤️ for the Laravel community

Documentation • Report Bug • Request Feature