quarasique/filament-translation-helper

A Filament plugin that provides automatic translations with fallback support for resources, forms and tables

1.0.3 2025-10-24 15:10 UTC

Requires

• php: ^8.2
• filament/filament: ^4.0
• illuminate/support: ^11.0|^12.0
• spatie/laravel-package-tools: ^1.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• phpunit/phpunit: ^11.0

MIT

• Quarasique

• i18n
• plugin
• translations
• laravel
• localization
• filament

README

A powerful Filament plugin that provides automatic translations with intelligent fallback support for resources, forms, tables, and navigation elements.

Features

• 🔄 Automatic Translation Discovery: Automatically translates field labels, section headings, and column names
• 🎯 Intelligent Fallback System: Falls back to common field translations or generated labels when specific translations aren't found
• 🌐 Multi-language Support: Built-in support for multiple locales with easy language switching
• 📝 BaseResource Class: Extended Resource class with automatic label translation
• 🎨 Language Switcher Component: Ready-to-use language switcher widget for your admin panel
• ⚙️ Configurable: Easily configure available locales and default language
• 🚀 Zero Configuration: Works out of the box with sensible defaults

Installation

Install the package via Composer:

composer require quarasique/filament-translation-helper

Publish the configuration and language files:

php artisan filament-translation-helper:publish

Or publish them separately:

# Publish configuration
php artisan vendor:publish --tag="filament-translation-helper-config"

# Publish language files
php artisan vendor:publish --tag="filament-translation-helper-lang"

Configuration

Available Locales

Configure available locales in config/filament-translation-helper.php:

return [
    'available_locales' => [
        'en' => 'English',
        'ru' => 'Русский',
        'es' => 'Español',
        'fr' => 'Français',
    ],

    'default_locale' => env('APP_LOCALE', 'en'),
];

Middleware Setup

Add the locale middleware to your Filament panel configuration:

use Quarasique\FilamentTranslationHelper\Http\Middleware\SetLocale;

public function panel(Panel $panel): Panel
{
    return $panel
        ->middleware([
            SetLocale::class,
            // ... other middleware
        ]);
}

Usage

Using BaseResource

Extend the BaseResource class instead of the default Filament Resource:

use Quarasique\FilamentTranslationHelper\Resources\BaseResource;

class UserResource extends BaseResource
{
    protected static ?string $model = User::class;
    
    // Labels are automatically translated from resources.user.label
    // and resources.user.plural_label
}

3. Use translateLabel() macro in forms and tables:

// In your form schema
TextInput::make('name')
    ->translateLabel() // Uses resources.user.fields.name
    ->required(),

// In your table columns  
TextColumn::make('email')
    ->translateLabel() // Uses resources.user.fields.email
    ->searchable(),

4. Create translation files:

// lang/en/resources.php
return [
    'user' => [
        'label' => 'User',
        'plural_label' => 'Users',
        'fields' => [
            'name' => 'Name',
            'email' => 'Email Address',
            'created_at' => 'Created At',
        ],
    ],
];

// lang/ru/resources.php  
return [
    'user' => [
        'label' => 'Пользователь',
        'plural_label' => 'Пользователи', 
        'fields' => [
            'name' => 'Имя',
            'email' => 'Email адрес',
            'created_at' => 'Дата создания',
        ],
    ],
];

How It Works

Translation Strategy

The plugin follows this lookup order for translations:

1. Resource-specific: resources.{resource-key}.fields.{field-name}
2. Common fields: common.fields.{field-name}
3. Base field name: common.fields.{base-name} (for fields like user.name → name)
4. Automatic fallback: Generated from field name (snake_case → Title Case)

This means you can have translations for specific resources, common field translations that work across all resources, or rely on automatic label generation.

Examples

Translation Examples

With translation files:

// lang/ru/common.php => 'fields' => ['first_name' => 'Имя']
TextInput::make('first_name') // → "Имя" (from translation)

// lang/en/common.php => 'fields' => ['first_name' => 'First Name']
TextInput::make('first_name') // → "First Name" (from translation)

Without translation files (automatic fallback):

TextInput::make('first_name') // → "First Name" (auto-generated)
TextInput::make('email_verified_at') // → "Email Verified At" (auto-generated)
Section::make('user_details') // → "User Details" (auto-generated)

Form Example

public static function form(Form $form): Form
{
    return $form
        ->schema([
            TextInput::make('name'), // Translated or "Name" fallback
            TextInput::make('email'), // Translated or "Email" fallback  
            TextInput::make('custom_field'), // Translated or "Custom Field" fallback
        ]);
}

Table Example

public static function table(Table $table): Table
{
    return $table
        ->columns([
            TextColumn::make('name'), // Auto-translated
            TextColumn::make('email'), // Auto-translated
            TextColumn::make('created_at'), // Auto-translated
        ]);
}

Advanced Usage

Manual Translation Helper

use Quarasique\FilamentTranslationHelper\Support\TranslationHelper;

// Get translation with fallback
$label = TranslationHelper::getWithFallback('resources.user.fields.full_name');
// Returns translation if exists, or "Full Name" as fallback

Language Switcher Configuration

Add the language switcher widget to your Filament panel:

use Quarasique\FilamentTranslationHelper\Components\LanguageSwitcher;

public function panel(Panel $panel): Panel
{
    return $panel
        ->widgets([
            LanguageSwitcher::class,
        ]);
}

Custom Resource Keys

By default, resources use snake_case of their class name. Override this:

class UserProfileResource extends BaseResource
{
    protected static function getResourceKey(): string
    {
        return 'user-profile'; // Uses resources.user-profile.*
    }
}

Commands

Generate resources with translation support:

php artisan filament-translation-helper:make-resource User

Publish translation templates:

php artisan filament-translation-helper:publish-translations

Configuration

The config file allows you to customize:

• Available locales
• Default and fallback locales
• Translation file structure
• Label formatting options

Translation File Structure

The plugin expects this structure in your language files:

// lang/{locale}/resources.php
return [
    'resource-key' => [
        'label' => 'Singular Label',
        'plural_label' => 'Plural Label',
        'fields' => [
            'field_name' => 'Field Label',
            // ...
        ],
        'actions' => [
            'action_name' => 'Action Label',
            // ...
        ],
    ],
];

Testing

Run the tests with:

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Quarasique
• All Contributors

License

The MIT License (MIT). Please see License File for more information.