Spatie Translatable Laravel Package

Technical Evaluation

Architecture Fit

• Modular and Extensible: The package integrates seamlessly with Spatie’s laravel-translatable package, leveraging its core translation logic while adding Filament-specific UI/UX layers (e.g., locale switchers, CRUD page support). This modularity allows for granular adoption—teams can use only the translation logic or the full Filament integration.
• Database-Agnostic: Compatible with Spatie’s translation storage strategies (JSON columns or separate tables), making it adaptable to existing database schemas without forced migrations.
• Filament-Centric: Built for Filament v4’s resource system, ensuring alignment with Filament’s page types (List, Create, Edit, View) and relation managers. Avoids reinventing Filament’s UI patterns (e.g., form handling, table columns).
• Trait-Based: Uses Laravel traits (HasTranslations, HasActiveLocaleSwitcher) to minimize boilerplate, adhering to Laravel’s dependency injection and service container principles.

Integration Feasibility

• Low-Coupling: The package injects translation capabilities via traits and service providers, reducing direct dependencies on Filament’s internals. This minimizes risk of conflicts with other Filament plugins or customizations.
• Resource-Level Configuration: Supports per-resource locale settings (e.g., setTranslatableLocales(['en', 'es'])), enabling selective adoption for specific models (e.g., only Post or Product).
• Field Compatibility: Works with Filament’s native fields but recommends third-party plugins (e.g., solution-forest/translate-field) for complex types (e.g., rich text, file uploads). This avoids forcing custom field implementations.
• Locale Switcher: Provides a session-based locale switcher for admins, but with caveats for complex fields (see Technical Risk).

Technical Risk

• Locale Switcher Limitations:
  • The README warns against using the locale switcher with "certain complex field types," which could lead to UX issues (e.g., unsaved translations, field misalignment). Mitigation: Use dedicated plugins like mvenghaus/translatable-inline for advanced fields.
  • Session-based persistence may conflict with Filament’s caching or multi-tab scenarios. Test thoroughly in staging.
• Filament Version Lock:
  • Hard dependency on Filament v4 (v3 requires a separate repo). Upgrades to Filament v5+ may require package updates or forks.
  • Risk of breaking changes if Filament’s resource API evolves (e.g., new page types, form handling).
• Database Schema Assumptions:
  • Assumes Spatie’s default translation storage (JSON columns or separate tables). Custom schemas (e.g., pivot tables) may require additional configuration.
  • No built-in support for fallback locales or machine translation—these would need custom logic.
• Performance:
  • JSON column storage can bloat database rows for highly translatable models. Monitor query performance with large datasets (e.g., 100+ languages).
  • Locale switcher adds session overhead; test with high-concurrency admin usage.

Key Questions for TPM

1. Locale Strategy:
   • Are we using Spatie’s laravel-translatable elsewhere in the app? If yes, this package will integrate cleanly. If no, evaluate the effort to adopt it.
   • Do we need fallback locales (e.g., default to en if es is missing)? This isn’t supported out-of-the-box.
2. Field Complexity:
   • Which Filament fields require translation (e.g., RichEditor, FileUpload)? If complex, budget time for third-party plugins or custom components.
3. Filament Ecosystem:
   • Are we using other Filament plugins that might conflict? Test early with filament/support and spatie/laravel-translatable.
4. Scaling:
   • How many translatable resources/languages will we support? Stress-test JSON column storage or consider separate tables for scalability.
5. Editor Workflow:
   • Will admins need to translate relations (e.g., comments for multilingual posts)? The package supports this, but UX may require additional tooling.
6. Maintenance:
   • Who will monitor for Filament v4 updates or Spatie package changes? Plan for periodic dependency reviews.
7. Alternatives:
   • If we need real-time translation APIs (e.g., DeepL), this package won’t suffice. Compare with spatie/laravel-translation-manager or custom solutions.

Integration Approach

Stack Fit

• Primary Stack: Laravel + Filament v4 + Spatie laravel-translatable.
  • Compatibility: High for apps already using these components. Minimal additional dependencies (e.g., filament/support, spatie/laravel-translatable).
  • Conflicts: Low risk if following Filament’s plugin guidelines. Test with composer why-not to check for version conflicts.
• Secondary Stack: Apps using Filament v3 must use the v3-specific repo.
• Database: Supports MySQL, PostgreSQL, SQLite (via Spatie). No vendor-specific features.

Migration Path

1. Prerequisites:
   • Ensure Laravel ≥ 8.x and Filament v4 are installed.
   • Install Spatie’s translatable package if not already present:

     composer require spatie/laravel-translatable
     

   • Publish Spatie’s config/migrations:

     php artisan vendor:publish --provider="Spatie\Translatable\TranslatableServiceProvider"
     

2. Install the Package:

   composer require lara-zeus/spatie-translatable
   

   Publish assets/config if needed:

   php artisan vendor:publish --provider="LaraZeus\SpatieTranslatable\SpatieTranslatableServiceProvider"
   

3. Configure Translatable Models:
   • Add traits to your Eloquent models:

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

   • Set default locales in config/translatable.php or per-resource:

     public static function getTranslatableLocales(): array
     {
         return ['en', 'es', 'fr'];
     }
     

4. Enable Filament Integration:
   • Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

     public function panel(Panel $panel): Panel
     {
         return $panel
             ->plugin(LaraZeus\SpatieTranslatable\FilamentPlugin::make());
     }
     

   • Add the HasTranslations trait to your Filament resources:

     use LaraZeus\SpatieTranslatable\Traits\HasTranslations;
     
     class PostResource extends Resource
     {
         use HasTranslations;
     
         public static function form(Form $form): Form
         {
             return $form->schema([
                 // Translatable fields will auto-adapt
             ]);
         }
     }
     

5. Test Locale Switcher:
   • Verify the locale switcher works on List/Edit pages. For complex fields, replace with a dedicated plugin (e.g., mvenghaus/translatable-inline).

Compatibility

• Filament Plugins: Test with plugins like filament-spatie-media-library or filament-notifications to ensure no conflicts in resource pages.
• Custom Fields: Non-translatable fields (e.g., Select, Checkbox) will work as-is. Translatable fields require compatible plugins or custom components.
• API Routes: The package focuses on Filament UI; API endpoints must be manually configured if needed (e.g., spatie/laravel-translatable provides API helpers).

Sequencing

1. Phase 1: Core Integration (1–2 sprints):
   • Install dependencies and configure Spatie’s translatable package.
   • Enable the Filament plugin and test basic CRUD translations (e.g., title, content).
   • Validate locale switcher UX for simple fields.
2. Phase 2: Advanced Features (1 sprint):
   • Implement relation translations (e.g., comments for posts).
   • Replace locale switcher with dedicated plugins for complex fields.
   • Add fallback locales or custom validation if needed.
3. Phase 3: Scaling (Ongoing):
   • Monitor database performance with JSON columns.
   • Optimize queries for large datasets (e.g., add indexes to translation keys).
   • Plan for Filament v5+ upgrades.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor spatie/laravel-translatable and lara-zeus/spatie-translatable for breaking changes. Use dependabot to track updates.
  • Filament v4 updates