Spatie Laravel Translatable Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require filament/spatie-laravel-translatable-plugin
   

   Publish the plugin assets (if needed):

   php artisan vendor:publish --provider="Filament\SpatieLaravelTranslatablePlugin\SpatieLaravelTranslatablePluginServiceProvider" --tag="spatie-laravel-translatable-plugin-assets"
   

2. Enable the Plugin Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Filament\SpatieLaravelTranslatablePlugin::make(),
           ]);
   }
   

3. First Use Case

   • Ensure your model uses Spatie\Translatable\HasTranslations trait.
   • Example model (app/Models/Post.php):

     use Spatie\Translatable\HasTranslations;
     
     class Post extends Model
     {
         use HasTranslations;
     
         public $translatable = ['title', 'content'];
     }
     

   • Create a Filament resource (e.g., php artisan make:filament-resource Post) and add the plugin to its form/tables.

Implementation Patterns

Workflow: Translatable Fields in Forms

1. Form Integration Use the plugin’s TranslatableFields widget in your resource’s Form:

   use Filament\Forms\Components\Fieldset;
   use Filament\SpatieLaravelTranslatablePlugin\Forms\Components\TranslatableFields;
   
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               TranslatableFields::make('translatable_content')
                   ->fields([
                       TextInput::make('title')->required(),
                       RichEditor::make('content'),
                   ])
                   ->availableLocales(['en', 'es', 'fr']),
           ]);
   }
   

2. Dynamic Locales Fetch locales dynamically from a config or database:

   TranslatableFields::make('translatable_content')
       ->availableLocales(config('app.available_locales'))
   

Workflow: Translatable Tables

1. Table Columns Display translatable columns in tables:

   use Filament\Tables\Columns\Column;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               Column::make('title')
                   ->translatable()
                   ->sortable(),
           ]);
   }
   

2. Default Locale Fallback Set a default locale for display:

   Column::make('title')
       ->translatable()
       ->defaultLocale('en')
   

Integration Tips

• Localization Middleware: Ensure your app uses app.locale middleware to handle locale switching.
• Resource Scoping: Scope resources to a specific locale if needed:

  public static function getEloquentQuery(Builder $query): Builder
  {
      return $query->setTranslationLocale(request()->get('locale', 'en'));
  }
  

• Validation: Validate translatable fields per locale:

  TranslatableFields::make('translatable_content')
      ->rules([
          'title' => ['required', 'min:3'],
          'content' => ['required', 'min:10'],
      ])
  

Gotchas and Tips

Pitfalls

1. Locale Mismatch

   • Issue: Translatable fields may not save if the locale isn’t explicitly set in the request or form.
   • Fix: Ensure app.locale is set or pass the locale via the form:

     TranslatableFields::make('translatable_content')
         ->locale(request()->get('locale', 'en'))
     

2. Missing Translations Table

   • Issue: Forgetting to run migrations for spatie/laravel-translatable (php artisan migrate).
   • Fix: Run migrations and ensure the translations table exists.

3. Nested Translatable Fields

   • Issue: Nested translatable fields (e.g., in nested forms) may not render correctly.
   • Fix: Use TranslatableFields only at the top level of the form schema.

Debugging

• Check Saved Data: Verify translations are saved in the translations table:

  SELECT * FROM translations WHERE translatable_id = {id};
  

• Log Locales: Debug locale issues with:

  \Log::info('Current locale:', request()->get('locale'));
  

Extension Points

1. Custom Locales Extend the plugin to support custom locale formats or validation:

   TranslatableFields::make('custom_translations')
       ->availableLocales(['en-US', 'es-MX'])
       ->customLocaleFormatter(fn ($locale) => ucfirst($locale));
   

2. Override Default Behavior Override the plugin’s default locale resolution in app/Providers/AppServiceProvider.php:

   use Filament\SpatieLaravelTranslatablePlugin\SpatieLaravelTranslatablePlugin;
   
   SpatieLaravelTranslatablePlugin::macro('getDefaultLocale', function () {
       return 'es';
   });
   

3. Add Custom Actions Attach locale-specific actions to resources:

   public static function getActions(Post $record): array
   {
       return [
           Action::make('translate')
               ->url(fn (Post $record) => route('filament.resources.posts.translate', $record))
               ->icon('heroicon-o-language'),
       ];
   }
   

Config Quirks

• Default Locale: Set the default locale in config/spatie/laravel-translatable.php:

  'default_locale' => 'en',
  

• Fallback Locale: Configure fallback locales for missing translations:

  'fallback_locales' => ['en'],