Filament Language Switcher

https://github.com/craft-forge/filament-language-switcher
Admin
A simple and elegant language switcher plugin for Filament admin panels that automatically detects...
Tokens:4,370
Snippets:38
Trust Score:4.8
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Plugin via Composer

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Installs the Filament Language Switcher plugin using Composer. This is the first step in integrating the plugin into your Filament project.

```bash
composer require craft-forge/filament-language-switcher
```

--------------------------------

### Install and Register Filament Language Switcher

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Install the package via Composer and register the plugin within your Filament PanelProvider to enable the language switcher functionality.

```bash
composer require craft-forge/filament-language-switcher
```

```php
// app/Providers/Filament/AdminPanelProvider.php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentLanguageSwitcherPlugin::make(),
        ]);
}
```

--------------------------------

### Configure Filament Language Switcher Plugin in AdminPanelProvider

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

This PHP code snippet demonstrates how to configure the Filament Language Switcher plugin within the `AdminPanelProvider.php` file. It shows both a minimal configuration for auto-detecting languages and a comprehensive setup with custom locales, flag display, and persistence options.

```php
// app/Providers/Filament/AdminPanelProvider.php
namespace App\Providers\Filament;

use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;
use Filament\Panel;
use Filament\PanelProvider;
use Filament\View\PanelsRenderHook;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->login()
            ->registration()
            ->passwordReset()
            ->plugins([
                // Minimal configuration - auto-detect languages
                FilamentLanguageSwitcherPlugin::make(),

                // Or full configuration
                FilamentLanguageSwitcherPlugin::make()
                    ->locales([
                        ['code' => 'en', 'name' => 'English', 'flag' => 'us'],
                        ['code' => 'es', 'name' => 'Español', 'flag' => 'es'],
                        ['code' => 'fr', 'name' => 'Français', 'flag' => 'fr'],
                        ['code' => 'de', 'name' => 'Deutsch', 'flag' => 'de'],
                        ['code' => 'pt_BR', 'name' => 'Português (Brasil)', 'flag' => 'br'],
                        ['code' => 'zh_CN', 'name' => '简体中文', 'flag' => 'cn'],
                    ])
                    ->showFlags(true)
                    ->showOnAuthPages()
                    ->rememberLocale(days: 90)
                    ->renderHook(PanelsRenderHook::USER_MENU_BEFORE),
            ]);
    }
}

```

--------------------------------

### Configure Plugin Instance

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Create and configure the plugin instance using method chaining. This allows for setting custom locales, enabling flags, and defining persistence settings.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

// Basic usage
FilamentLanguageSwitcherPlugin::make()

// Full configuration example
FilamentLanguageSwitcherPlugin::make()
    ->locales(['en', 'fr', 'de', 'es'])
    ->showFlags(true)
    ->showOnAuthPages()
    ->rememberLocale(days: 30)
    ->renderHook(PanelsRenderHook::USER_MENU_BEFORE)
```

--------------------------------

### Configure Flag Icon Visibility

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Controls whether flag icons are displayed next to language names in the switcher. Setting this to `false` will only show the language names, providing a cleaner interface if flags are not desired.

```php
FilamentLanguageSwitcherPlugin::make()
    ->showFlags(false)
```

--------------------------------

### Show Language Switcher on Auth Pages

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Configures the plugin to display the language switcher component on authentication-related pages such as login, registration, and password reset. This ensures users can select their preferred language even before logging in. It can be enabled with a simple boolean or configured with specific locales and persistent locale settings.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

// Enable language switcher on auth pages
FilamentLanguageSwitcherPlugin::make()
    ->showOnAuthPages()

// Explicit boolean parameter
FilamentLanguageSwitcherPlugin::make()
    ->showOnAuthPages(true)

// Full auth page configuration with persistent locale
FilamentLanguageSwitcherPlugin::make()
    ->locales(['en', 'fr', 'de', 'es'])
    ->showOnAuthPages()
    ->rememberLocale()
```

--------------------------------

### Configure Display on Auth Pages

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Enables the language switcher to be visible on authentication-related pages such as login, registration, and password reset forms. This ensures users can select their preferred language even before logging in.

```php
FilamentLanguageSwitcherPlugin::make()
    ->showOnAuthPages()
```

--------------------------------

### Language Switching Route and URL Generation

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

The plugin registers a route (`filament-language-switcher.switch`) that handles the actual language switching process. This route updates the session, optionally sets a cookie for persistence, dispatches the `LocaleChanged` event, and redirects the user back. You can generate URLs for this route programmatically or use them in direct links.

```php
// Route: GET /filament/switch-language/{code}
// Name: filament-language-switcher.switch

// The route handler performs these actions:
// 1. Stores the locale in the session
// 2. Optionally sets a persistent cookie (if rememberLocale() is enabled)
// 3. Dispatches the LocaleChanged event
// 4. Redirects back to the previous page

// Generate the route URL programmatically
$switchUrl = route('filament-language-switcher.switch', ['code' => 'fr']);
// Returns: /filament/switch-language/fr

// Manual language switch link (if needed outside the dropdown)
// <a href="{{ route('filament-language-switcher.switch', ['code' => 'de']) }}">
//     Switch to German
// </a>
```

--------------------------------

### Configure Custom Render Hook

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Allows customization of the position where the language switcher appears within the Filament panel. You can choose from various predefined render hooks to integrate the switcher seamlessly.

```php
use Filament\View\PanelsRenderHook;

FilamentLanguageSwitcherPlugin::make()
    ->renderHook(PanelsRenderHook::USER_MENU_PROFILE_AFTER)
```

--------------------------------

### Define Available Locales

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Specify the languages available for selection. You can provide simple locale codes, detailed arrays with custom names and flags, or dynamic closures for database-driven configurations.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

// Simple locale codes
FilamentLanguageSwitcherPlugin::make()
    ->locales(['en', 'fr', 'de', 'pt_BR', 'zh_CN'])

// Full control with custom names and flags
FilamentLanguageSwitcherPlugin::make()
    ->locales([
        ['code' => 'en', 'name' => 'English', 'flag' => 'us'],
        ['code' => 'fr', 'name' => 'Français', 'flag' => 'fr'],
        ['code' => 'de', 'name' => 'Deutsch', 'flag' => 'de'],
        ['code' => 'pt_BR', 'name' => 'Português (Brasil)', 'flag' => 'br'],
    ])

// Dynamic locales from database
FilamentLanguageSwitcherPlugin::make()
    ->locales(fn () => Language::where('active', true)->pluck('code')->toArray())
```

--------------------------------

### Configure Locale Persistence

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Enables the language switcher to remember the user's selected locale across sessions by storing it in a cookie. This provides a persistent language preference for users.

```php
FilamentLanguageSwitcherPlugin::make()
    ->rememberLocale()          // forever
    ->rememberLocale(days: 30)  // for 30 days
```

--------------------------------

### Configure Locales Manually

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Manually defines the list of available locales for the language switcher. This allows for precise control over which languages are offered to users. Supports simple locale codes or detailed configurations with names and flags.

```php
FilamentLanguageSwitcherPlugin::make()
    ->locales(['en', 'fr', 'de'])
```

```php
FilamentLanguageSwitcherPlugin::make()
    ->locales([
        ['code' => 'en', 'name' => 'English', 'flag' => 'us'],
        ['code' => 'fr', 'name' => 'Français', 'flag' => 'fr'],
        ['code' => 'de', 'name' => 'Deutsch', 'flag' => 'de'],
    ])
```

```php
FilamentLanguageSwitcherPlugin::make()
    ->locales(fn () => Language::pluck('code')->toArray())
```

--------------------------------

### Set Render Hook Placement

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Control the UI placement of the language switcher by passing a Filament render hook constant to the renderHook method.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;
use Filament\View\PanelsRenderHook;

// Position in user menu
FilamentLanguageSwitcherPlugin::make()
    ->renderHook(PanelsRenderHook::USER_MENU_PROFILE_AFTER)

// Position in sidebar footer
FilamentLanguageSwitcherPlugin::make()
    ->renderHook(PanelsRenderHook::SIDEBAR_FOOTER)
```

--------------------------------

### Register Plugin in Filament Panel

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Registers the Filament Language Switcher plugin within your Filament panel configuration, typically in the `AdminPanelProvider`. This makes the plugin's functionality available in your admin panel.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentLanguageSwitcherPlugin::make(),
        ]);
}
```

--------------------------------

### Persist User Locale

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Configure the plugin to remember the user's selected language across sessions using cookies. You can set a specific duration in days or store it indefinitely.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

// Remember locale forever
FilamentLanguageSwitcherPlugin::make()
    ->rememberLocale()

// Remember locale for 30 days
FilamentLanguageSwitcherPlugin::make()
    ->rememberLocale(days: 30)
```

--------------------------------

### Listen for Locale Changed Event

Source: https://github.com/craft-forge/filament-language-switcher/blob/main/README.md

Handles the `LocaleChanged` event dispatched by the plugin whenever a user switches their locale. This allows for custom actions, such as updating user preferences or logging the change.

```php
use CraftForge\FilamentLanguageSwitcher\Events\LocaleChanged;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(LocaleChanged::class, function (LocaleChanged $event) {
        // auth()->user()->setLocale($event->newLocale);
        // Log::info("Locale changed from {$event->oldLocale} to {$event->newLocale}");
    });
}
```

--------------------------------

### Set Application Locale Middleware

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

The `SetLocale` middleware automatically applies the user's selected language to the application for the current request. It prioritizes the session locale, then a cookie (if `rememberLocale()` is enabled), and finally falls back to the application's default locale. This middleware is automatically registered.

```php
// The middleware priority for locale resolution:
// 1. Session locale (set when user switches language)
// 2. Cookie locale (if rememberLocale() is enabled)
// 3. Application default locale (config/app.php)

// Middleware implementation (automatically registered)
namespace CraftForge\FilamentLanguageSwitcher\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;

class SetLocale
{
    public function handle(Request $request, Closure $next): mixed
    {
        $locale = config('app.locale', 'en');

        if ($request->hasSession()) {
            $sessionLocale = $request->session()->get('locale');

            if ($sessionLocale) {
                $locale = $sessionLocale;
            } elseif ($cookieLocale = $request->cookie('filament_language_switcher_locale')) {
                $locale = $cookieLocale;
                $request->session()->put('locale', $locale);
            }
        }

        App::setLocale($locale);

        return $next($request);
    }
}
```

--------------------------------

### Control Display of Country Flags

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Determines whether country flag icons are displayed next to language names in the switcher. By default, flags are shown. This setting allows you to hide them for a cleaner interface, showing only the language names.

```php
use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

// Hide flags, show only language names
FilamentLanguageSwitcherPlugin::make()
    ->showFlags(false)

// Explicitly show flags (default behavior)
FilamentLanguageSwitcherPlugin::make()
    ->showFlags(true)
```

--------------------------------

### Handle Locale Changed Event

Source: https://context7.com/craft-forge/filament-language-switcher/llms.txt

Listens for the `LocaleChanged` event dispatched by the plugin whenever a user switches their locale. This allows for custom actions like persisting the user's locale preference in their profile or logging the change. The event provides both the new and previous locale codes.

```php
// app/Providers/AppServiceProvider.php
use CraftForge\FilamentLanguageSwitcher\Events\LocaleChanged;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

public function boot(): void
{
    Event::listen(LocaleChanged::class, function (LocaleChanged $event) {
        // Access the new and old locale
        $newLocale = $event->newLocale;  // e.g., 'fr'
        $oldLocale = $event->oldLocale;  // e.g., 'en'

        // Save to authenticated user's profile
        if ($user = auth()->user()) {
            $user->update(['locale' => $event->newLocale]);
        }

        // Log the change
        Log::info("Locale changed from {$event->oldLocale} to {$event->newLocale}");
    });
}

// Alternative: Using a dedicated listener class
// app/Listeners/SaveUserLocale.php
namespace App\Listeners;

use CraftForge\FilamentLanguageSwitcher\Events\LocaleChanged;

class SaveUserLocale
{
    public function handle(LocaleChanged $event): void
    {
        if ($user = auth()->user()) {
            $user->update(['preferred_locale' => $event->newLocale]);
        }
    }
}

// Register in EventServiceProvider
protected $listen = [
    LocaleChanged::class => [
        SaveUserLocale::class,
    ],
];
```
Tokens:
Raw