Localization Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require moox/localization
   php artisan localization:install
   

   This creates the localizations table and publishes config files.

2. Configure Locales Define locales in config/localization.php:

   'locales' => [
       'en' => 'English',
       'de' => 'Deutsch',
       // ...
   ],
   

3. First Use Case Use the Language Switcher in your Filament panel:

   ->renderHook(
       \Filament\View\PanelsRenderHook::USER_MENU_BEFORE,
       fn () => \Illuminate\Support\Facades\Blade::render('@livewire(\'language-switch\',[\'context\'=>\'backend\'])')
   )
   

4. Enable Admin Panel Set 'enable-panel' => true in config/localization.php to access /localization.

Implementation Patterns

Core Workflows

1. Model Localization Extend moox/localization with astrotomic/laravel-translatable for multi-language models:

   use Astrotomic\Translatable\Contracts\Translatable;
   use Astrotomic\Translatable\Traits\Translatable;
   
   class Post extends Model implements Translatable
   {
       use Translatable;
       public $translatable = ['title', 'content'];
   }
   

2. Route Localization Use the routing_path column in the localizations table to manage URL slugs per locale:

   // In a controller
   $localization = Localization::where('routing_path', request()->path())->first();
   

3. Livewire Integration

   • Language Switcher: Use the provided Livewire component for frontend/backend:

     @livewire('language-switch', ['context' => 'frontend'])
     

   • Localization Panel: Manage translations via /localization (Filament-based).

4. SEO Meta Tags Dynamically fetch title, description, and keywords from the localizations table:

   $meta = Localization::where('language_id', app()->getLocale())->first();
   

Integration Tips

• Filament Admin Panel: Leverage the LocalizationPanelProvider for a dedicated UI.
• Middleware: Use moox/localization's middleware to enforce locale-based routing:

  Route::middleware(['localization'])->group(function () {
      // Routes here will respect locale
  });
  

• API Responses: Localize API responses using app()->setLocale() or middleware.

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • Ensure astrotomic/laravel-translatable and moox/core are installed. The package will not work without them.
   • Run composer require astrotomic/laravel-translatable moox/core if missing.

2. Locale Mismatch

   • The language_id in the localizations table must match your config/app.php locales. Use app()->getLocales() to verify.
   • Debug with:

     dd(app()->getLocale(), Localization::pluck('language_id')->toArray());
     

3. Route Conflicts

   • The routing_path column is used for locale-specific URLs. Avoid duplicate paths across locales.
   • Test with:

     php artisan route:list | grep localization
     

4. Livewire Context Issues

   • The language-switch Livewire component requires a context parameter ('frontend' or 'backend'). Omitting it may cause errors.

Debugging

• Panel Not Loading:

  • Verify 'enable-panel' => true in config/localization.php.
  • Check Filament panel registration in AppServiceProvider:

    Filament::registerPanelProviders([
        \Moox\Localization\Providers\LocalizationPanelProvider::class,
    ]);
    

• Translations Not Updating:

  • Clear cached translations:

    php artisan view:clear
    php artisan cache:clear
    

Extension Points

1. Custom Fields Extend the localizations table by publishing migrations:

   php artisan vendor:publish --provider="Moox\Localization\LocalizationServiceProvider" --tag="migrations"
   

   Then modify the published migration.

2. Override Livewire Components Publish the Livewire views:

   php artisan vendor:publish --provider="Moox\Localization\LocalizationServiceProvider" --tag="views"
   

   Customize resources/views/vendor/moox/localization/language-switch.blade.php.

3. Add Custom Logic Bind events in EventServiceProvider:

   protected $listen = [
       \Moox\Localization\Events\LocaleSwitched::class => [
           \App\Listeners\HandleLocaleSwitch::class,
       ],
   ];
   

Performance Tips

• Eager Load Localizations:

  $localizations = Localization::with(['translations'])->get();
  

• Cache SEO Meta Tags:

  Cache::remember("meta_{$locale}", now()->addHours(1), function () use ($locale) {
      return Localization::where('language_id', $locale)->first();
  });