README

Comprehensive localization and internationalization package for Laravel applications, providing translation files, automatic locale detection, and timezone handling.

Features

🌍 Multi-Language Support: Pre-configured translations for English and Arabic
🔄 Automatic Locale Detection: Smart locale detection from multiple sources
⏰ Timezone Handling: Request-based timezone configuration
🎯 Middleware: Ready-to-use middlewares for locale and timezone
📦 Laravel Integration: Seamless integration with Laravel's translation system
🚀 Easy to Extend: Simple to add new languages and translations

Installation

This package is included in the Pixielity Framework. If you need to install it separately:

composer require pixielity/localization

The service provider will be auto-discovered by Laravel.

Configuration

Locale Configuration

Create a config/localization.php file:

return [
    'default' => 'en',
    'auto_detect' => true,
    'headers' => ['x-language', 'x-locale', 'locale', 'accept-language'],
    'query_params' => ['lang', 'locale'],
    'locales' => [
        'en' => ['enabled' => true, 'name' => 'English'],
        'ar' => ['enabled' => true, 'name' => 'Arabic'],
        'fr' => ['enabled' => false, 'name' => 'French'],
    ],
];

Timezone Configuration

Add to your .env:

APP_TIMEZONE=UTC
APP_TIMEZONE_HEADER=X-Timezone

Usage

Applying Middlewares

Global Middleware

In bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->append([
        \Pixielity\Localization\Middlewares\SetLocale::class,
        \Pixielity\Localization\Middlewares\TimezoneMiddleware::class,
    ]);
})

Route Middleware

Route::middleware(['set.locale', 'timezone'])->group(function () {
    Route::get('/users', [UserController::class, 'index']);
});

Using Translations

// In controllers or views
__('localization::validation.required');
__('localization::crud.created');

// With parameters
__('localization::validation.min.string', ['attribute' => 'password', 'min' => 8]);

Setting Locale Programmatically

// Set locale
app()->setLocale('ar');

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

Client-Side Usage

Setting Locale via Header

fetch("/api/users", {
  headers: {
    "X-Language": "ar",
  },
});

Setting Locale via Query Parameter

fetch("/api/users?lang=ar");

Setting Locale via Path Segment

fetch("/ar/api/users");

Setting Timezone

fetch("/api/users", {
  headers: {
    "X-Timezone": Intl.DateTimeFormat().resolvedOptions().timeZone,
  },
});

Locale Detection Priority

The SetLocale middleware detects locale in the following priority order:

User Preference (highest priority)
- Authenticated user's saved locale preference
- Stored in users.locale column
Query Parameters
- ?lang=ar or ?locale=ar
Path Segment
- /ar/api/users
Route Parameters
- {locale}/users
Request Headers
- X-Language, X-Locale, Accept-Language
Default Locale (fallback)
- From configuration

Available Translations

English (en)

crud.php - CRUD operation messages
validation.php - Validation messages

Arabic (ar)

crud.php - CRUD operation messages (RTL)
validation.php - Validation messages (RTL)

Adding New Languages

Create a new language directory:

mkdir packages/Framework/src/Localization/src/lang/fr

Add translation files:

// packages/Framework/src/Localization/src/lang/fr/crud.php
return [
    'created' => 'Créé avec succès',
    'updated' => 'Mis à jour avec succès',
    // ...
];

Enable in configuration:

'locales' => [
    'fr' => ['enabled' => true, 'name' => 'French'],
],

Middleware Details

SetLocale Middleware

Automatically sets the application locale based on request data.

Alias: set.locale
Priority: 50

Features:

Multi-source locale detection
User preference support
Validation of enabled locales
Logging context integration

TimezoneMiddleware

Sets the application timezone based on request headers or user preferences.

Alias: timezone
Priority: 45