Filament Language Switcher Laravel Package

Technical Evaluation

Architecture Fit

• Filament-Centric Design: The package is purpose-built for Filament admin panels (v3.x–5.x), aligning with modern Laravel admin UI patterns. It leverages Filament’s plugin system, ensuring seamless integration without disrupting core functionality.
• Zero-Config Philosophy: Auto-detection of translations reduces manual setup, but requires Craft CMS or Filament-compatible translation files (e.g., resources/lang/) to function optimally. Misalignment here could lead to silent failures.
• Event-Driven Locale Switching: Supports locale.changed events, enabling downstream systems (e.g., API clients, frontend JS) to react to language changes. Critical for multi-channel apps (admin + frontend).
• Session/Cookie Persistence: Uses Laravel’s session system, which is standard but may conflict with custom session drivers or multi-server setups.

Integration Feasibility

• Filament Dependency: Hard requirement for Filament 3.x–5.x. Non-Filament Laravel apps (e.g., Livewire, Inertia) would need wrapper logic.
• Craft CMS Synergy: Optimized for Craft CMS (given the craft-forge namespace), but works with any Filament-based app. Translation file structure must match Filament’s expectations (e.g., filament/locales/{locale}.json).
• PHP 8.1+: Modern PHP features (e.g., enums, attributes) may introduce minor deprecation risks if the app uses older Laravel versions (e.g., <9.x).

Technical Risk

• Translation File Assumptions: Auto-detection relies on specific file naming/conventions. Custom locales (e.g., non-Filament JSON files) require manual configuration, adding complexity.
• Flag Icon Dependency: Uses a third-party flag icon set (likely laravel-flag-icons). If this package is deprecated or removed, the UI could break.
• Session Handling: Cookie-based persistence might clash with SSO systems or apps using custom session backends (e.g., Redis clusters).
• Dark Mode Support: Visual regression risk if Filament’s theme system changes (e.g., CSS classes for dark mode).

Key Questions

1. Translation Strategy:
   • Are Filament translations stored in the default resources/lang/ or a custom location?
   • How are non-Filament translations (e.g., frontend, API) managed? Will they sync with the switcher?
2. Locale Scope:
   • Should the switcher apply to all users or respect user-specific locales (e.g., via app()->locale)?
3. Performance:
   • Will the auto-detection of locales add noticeable overhead during panel initialization?
4. Fallback Behavior:
   • What happens if no translations are detected? Does it default to app()->locale or show an error?
5. Multi-Tenant/Region:
   • Does the app need region-specific locales (e.g., en-US, en-GB)? The package supports this but may require manual locale mapping.
6. Testing:
   • Are there existing tests for locale change events and session persistence? How would we verify edge cases (e.g., concurrent locale switches)?

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Filament-powered admin panels in Laravel apps, especially those using Craft CMS or similar translation-heavy systems.
• Compatibility Matrix:

  Component	Supported Versions	Notes
  Laravel	9.x–11.x	PHP 8.1+ required
  Filament	3.x–5.x	Plugin system must be enabled
  PHP	8.1–8.3	No breaking changes in target range
  Translation Files	Filament JSON format	Custom formats need manual config

• Non-Filament Apps: Requires wrapper logic to expose the switcher as a standalone component (e.g., via Blade directives or Livewire).

Migration Path

1. Pre-Integration:
   • Audit existing translation files to ensure they match Filament’s expected structure.
   • Verify Filament version compatibility (e.g., test with filament/filament:^5.0).
2. Installation:

   composer require craft-forge/filament-language-switcher
   

   • Add to AdminPanelProvider (or other panel providers):

     ->plugins([
         FilamentLanguageSwitcherPlugin::make()
             ->locales(['en', 'fr', 'es']) // Optional: override auto-detection
             ->cookieName('locale')         // Optional: customize cookie
     ])
     

3. Post-Integration:
   • Test locale switching in auth pages (if enabled).
   • Verify locale.changed events fire correctly (e.g., log or broadcast changes).
   • Check dark mode and flag icons render as expected.

Compatibility

• Filament Plugins: Other plugins using locales (e.g., spatie/laravel-translatable) should not conflict if they respect Laravel’s app()->locale.
• Middleware: If using locale middleware (e.g., SetLocale), ensure it doesn’t override the switcher’s session cookie.
• Frontend: For SPA integration, emit the locale.changed event to frontend via Laravel Echo or a custom API endpoint.

Sequencing

1. Phase 1: Basic integration (auto-detected locales, session persistence).
2. Phase 2: Customize locales/flags and test edge cases (e.g., missing translations).
3. Phase 3: Extend to frontend (if needed) via API/events.
4. Phase 4: Monitor performance impact (e.g., locale detection latency).

Operational Impact

Maintenance

• Dependencies:
  • Minimal: Only requires Filament and PHP 8.1+. No external services.
  • Flag Icons: Monitor laravel-flag-icons for updates/removals.
• Updates:
  • Follow Filament’s release cycle. The package is actively maintained (last release: 2026-03-04).
  • Backward Compatibility: MIT license implies low risk, but test major version bumps.
• Configuration Drift:
  • Manual locale overrides (e.g., ->locales()) may need updates if translation files change.

Support

• Debugging:
  • Auto-Detection Failures: Check storage/logs/laravel.log for missing locale files.
  • Event Issues: Verify locale.changed listeners are registered.
• User Feedback:
  • Flag icon visibility issues (e.g., missing fonts) may require CSS overrides.
  • Test with RTL languages if applicable (e.g., Arabic).
• Fallbacks:
  • Implement a default locale in config/app.php as a safety net.

Scaling

• Performance:
  • Locale auto-detection is O(n) where n = number of locale files. For large apps, consider caching the detected locales (e.g., in a config file).
  • Session cookie writes are minimal overhead but could scale with concurrent locale changes.
• Multi-Server:
  • Session driver (e.g., Redis) must support cookie-based persistence. Test in staging with load.
• Edge Cases:
  • High Traffic: Rate-limit locale changes if abuse is a risk (e.g., via middleware).
  • Geodistributed Apps: Ensure cookie domain/path is configured for CDN/edge caching.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Document the translation file structure required for auto-detection.
  • Provide a troubleshooting guide for common issues (e.g., "Why aren’t my locales showing?").
• Testing Checklist:
  1. Install and verify basic functionality.
  2. Test locale switching in auth pages (if enabled).
  3. Validate locale.changed events.
  4. Check dark mode and flag icons.
  5. Load test with concurrent users.
• Rollback Plan:
  • If issues arise, remove the plugin from panel() and revert to manual locale handling (e.g., middleware).