README

Automatic locale detection middleware and translation traits for Laravel APIs. Detects Accept-Language header and provides HasTranslations trait for models with JSON-stored translations.

Features

• Automatically detects user's preferred language from Accept-Language header
• Sets Laravel's app locale based on the detected language
• Provides HasTranslations trait for models with JSON translation columns
• Provides TranslatableResource trait for API resources
• Supports locale fallbacks
• Configurable supported locales
• Excludes specific routes from locale detection

Requirements

• PHP 8.2+
• Laravel 11.0+ or 12.0+

Installation

composer require jeromejhipolito/laravel-translation-middleware

The package will auto-register its service provider.

Configuration

Publish the configuration file:

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

This will create config/translation.php:

return [
    // HTTP header name for locale detection
    'header' => env('TRANSLATION_HEADER', 'Accept-Language'),

    // Default locale when no header is provided
    'default' => env('TRANSLATION_DEFAULT', 'en'),

    // Supported locales (empty array = accept all)
    'supported_locales' => ['en', 'ja', 'ko', 'zh', 'es', 'fr', 'de', 'pt', 'it', 'ru'],

    // Fallback when translation not available
    'fallback' => env('TRANSLATION_FALLBACK', 'en'),

    // Column suffix for translations (e.g., title_translations)
    'column_suffix' => '_translations',

    // Parse 'en-US' to 'en' (true) or keep full code (false)
    'parse_language_only' => true,

    // Routes to skip locale detection
    'excluded_routes' => [],
];

Usage

1. Register the Middleware

Add the middleware to your routes in bootstrap/app.php:

use JeromeJHipolito\TranslationMiddleware\Middleware\SetLocaleMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->api(append: [
        SetLocaleMiddleware::class,
    ]);
})

2. Add HasTranslations Trait to Models

use Illuminate\Database\Eloquent\Model;
use JeromeJHipolito\TranslationMiddleware\Traits\HasTranslations;

class Article extends Model
{
    use HasTranslations;

    protected $fillable = [
        'title',
        'content',
        'title_translations',
        'content_translations',
    ];

    protected $casts = [
        'title_translations' => 'array',
        'content_translations' => 'array',
    ];

    // Define which attributes are translatable
    protected array $translatable = ['title', 'content'];
}

3. Database Migration

Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');                    // Default value
    $table->json('title_translations')->nullable();  // Translations
    $table->text('content');
    $table->json('content_translations')->nullable();
    $table->timestamps();
});

4. Store Translations

$article = Article::create([
    'title' => 'Hello World',
    'content' => 'This is the content.',
]);

// Set individual translations
$article->setTranslation('title', 'ja', 'こんにちは世界');
$article->setTranslation('title', 'ko', '안녕하세요 세계');
$article->save();

// Or set multiple at once
$article->setTranslations('title', [
    'ja' => 'こんにちは世界',
    'ko' => '안녕하세요 세계',
    'zh' => '你好世界',
]);
$article->save();

5. Retrieve Translations

// Uses current app locale (set by middleware)
$title = $article->getTranslation('title');

// Specify locale explicitly
$title = $article->getTranslation('title', 'ja');

// Get all translations
$translations = $article->getTranslations('title');
// ['ja' => 'こんにちは世界', 'ko' => '안녕하세요 세계']

// Check if translation exists
if ($article->hasTranslation('title', 'fr')) {
    // ...
}

// Get available locales
$locales = $article->getAvailableLocales('title');
// ['ja', 'ko', 'zh']

6. Use TranslatableResource in API Resources

use Illuminate\Http\Resources\Json\JsonResource;
use JeromeJHipolito\TranslationMiddleware\Traits\TranslatableResource;

class ArticleResource extends JsonResource
{
    use TranslatableResource;

    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->translated('title'),      // Auto-translated
            'content' => $this->translated('content'),  // Auto-translated
            'available_translations' => $this->availableTranslations('title'),
            'created_at' => $this->created_at,
        ];
    }
}

Client-Side Usage

Send the preferred language in the Accept-Language header:

fetch('/api/articles/1', {
    headers: {
        'Accept-Language': 'ja',
    },
});

// Response:
// {
//     "id": 1,
//     "title": "こんにちは世界",
//     "content": "これはコンテンツです",
//     "available_translations": ["ja", "ko", "zh"]
// }

API Reference

HasTranslations Trait Methods

TranslatableResource Trait Methods

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

Credits

• Jerome Hipolito