Laravel Filament Translatable Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require novius/laravel-filament-translatable
   

   Publish the package config (if needed):

   php artisan vendor:publish --provider="Novius\FilamentTranslatable\FilamentTranslatableServiceProvider"
   

2. Enable Translatable Fields Add the trait to your Filament resource model:

   use Novius\FilamentTranslatable\Traits\Translatable;
   
   class Post extends Model
   {
       use Translatable;
   }
   

3. Define Translatable Fields In your Filament resource, use the translatable() method:

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               TextInput::make('title')
                   ->translatable(),
               RichEditor::make('content')
                   ->translatable(),
           ]);
   }
   

4. First Use Case

   • Create a multilingual resource (e.g., Post).
   • Add translatable fields to the form.
   • Save records with translations (e.g., title in English and French).

Implementation Patterns

Workflow: Managing Translations

1. Field Configuration Use translatable() on Filament fields to enable translations:

   TextInput::make('description')
       ->translatable()
       ->columnSpanFull()
       ->required();
   

2. Locale Selection Dynamically set the current locale in the form:

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               Select::make('locale')
                   ->options(['en', 'fr', 'es'])
                   ->default('en'),
               // Translatable fields...
           ]);
   }
   

3. Table Integration Display translations in the table:

   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               TextColumn::make('title')
                   ->translatable(),
           ]);
   }
   

4. Bulk Actions Use translatable() with bulk actions (e.g., edit, delete) to ensure translations are preserved:

   public static function getBulkActions(): array
   {
       return [
           Tables\Actions\DeleteBulkAction::make()
               ->requiresConfirmation(),
       ];
   }
   

Integration Tips

• Middleware: Use app()->setLocale() to enforce locale-specific views.
• APIs: Extend the package to support API responses with translations:

  public function toArray()
  {
      return [
          'title' => $this->getTranslation('title', app()->getLocale()),
      ];
  }
  

• Validation: Validate translations separately:

  $this->validate([
      'title_en' => 'required|string|max:255',
      'title_fr' => 'required|string|max:255',
  ]);
  

Gotchas and Tips

Pitfalls

1. Missing Locale Fallback

   • If no translation exists for the current locale, the field may return null. Configure a fallback:

     $post->getTranslation('title', 'en'); // Fallback to English
     

2. Database Schema Mismatch

   • Ensure your database tables support translatable fields (e.g., title_en, title_fr). Run migrations if needed:

     php artisan migrate
     

3. Caching Issues

   • Clear Filament and route caches after adding translatable fields:

     php artisan filament:cache:clear
     php artisan optimize:clear
     

4. Field Overrides

   • Avoid overriding translatable fields in child classes without reapplying translatable():

     // ❌ Broken
     TextInput::make('title')->required();
     
     // ✅ Fixed
     TextInput::make('title')->translatable()->required();
     

Debugging

• Check Translations Dump translations to debug:

  dd($model->getTranslations());
  

• Log Missing Fields Enable debug mode to log missing translatable fields:

  config(['filament-translatable.debug' => true]);
  

Extension Points

1. Custom Storage Override the default storage (e.g., JSON column):

   use Novius\FilamentTranslatable\Contracts\TranslatableStorage;
   
   class CustomStorage implements TranslatableStorage
   {
       public function store($model, $field, $locale, $value)
       {
           // Custom logic
       }
   }
   
   // Register in config/filament-translatable.php
   

2. Dynamic Locales Fetch locales dynamically (e.g., from a config file):

   $locales = config('app.available_locales');
   

3. Localization Hooks Use Filament’s hooks to modify translations:

   Filament::serving(function () {
       Filament::registerFormModification(
           PostResource::class,
           fn (Form $form) => $form->schema([
               // Modify translatable fields here
           ])
       );
   });
   

4. Testing Test translations with Pest:

   it('saves translations', function () {
       $post = Post::create(['title_en' => 'Hello']);
       expect($post->getTranslation('title', 'en'))->toBe('Hello');
   });