Filament Translator Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require syriable/filament-translator
   

2. Register the plugin in your Filament panel:

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

3. Use convention-based labels in your Filament components (e.g., forms, tables, actions). The package will automatically derive translation keys from your class structure.

First Use Case

Translate a Filament form action label without hardcoding strings:

use Filament\Forms\Components\SubmitAction;

SubmitAction::make('submit')
    ->label(); // Automatically resolves to `livewire.{form}.actions.submit.label`

The package will generate the missing translation key in your lang/{locale}/livewire/{form}.php file during development if createMissingTranslationKeys() is enabled.

Implementation Patterns

Convention-Based Workflow

1. Define components using Filament’s builder methods (e.g., TextInput, Select, Actions).
2. Let the package derive keys from your class hierarchy and component names:
   • App\Filament\Resources\PostResource\Pages\CreatePost → filament.resources.post.pages.create
   • App\Filament\Resources\PostResource\Pages\EditPost\Actions\DeletePost → filament.resources.post.pages.edit.actions.delete
3. Access translations via Laravel’s __() helper or Filament’s built-in translation system.

Integration with Filament Components

Forms

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->label(); // Resolves to `filament.forms.components.name.label`

Tables

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->label(); // Resolves to `filament.tables.columns.title.label`

Actions

use Filament\Tables\Actions\Action;

Action::make('view')
    ->label(); // Resolves to `filament.tables.actions.view.label`

Path Aliases for Custom Namespaces

Map non-standard namespaces (e.g., Livewire) to lang paths:

TranslatorPlugin::make()
    ->pathAliases([
        'App\\Livewire' => 'livewire',
    ]);

Now, App\Livewire\Auth\Login resolves to livewire.auth.login.

Base Classes for Reusability

Extend provided base classes to enforce translation conventions:

use Syriable\Filament\Pages\TranslatablePage;

class CreatePost extends TranslatablePage
{
    // All labels will auto-resolve from conventions
}

Automatic Key Creation (Local Dev)

Enable scaffolding of missing translation keys:

TranslatorPlugin::make()
    ->createMissingTranslationKeys();

This generates stubs like:

// lang/en/livewire/auth/login.php
return [
    'form' => [
        'components' => [
            'actions' => [
                'forgot-password' => [
                    'label' => 'Forgot Password',
                ],
            ],
        ],
    ],
];

Gotchas and Tips

Pitfalls

1. Double Booting:

   • Avoid manually calling registerDefaults() if TranslatorPlugin is already registered on the panel.
   • The package is idempotent, but redundant calls may clutter logs.

2. Path Aliases in Guest Routes:

   • Standalone Livewire pages (e.g., /login) require manual booting:

     app(ConventionRegistry::class)->registerDefaults();
     

   • Ensure TranslatorPlugin is registered on the default panel if guest routes need custom aliases.

3. Hint Icon Tooltips:

   • Single-argument hintIcon() may not work in older Filament versions (pre-4.x without func_num_args() guard).
   • Test with:

     TextInput::make('password')
         ->hintIcon('heroicon-o-question-mark-circle');
     

     If the tooltip disappears, upgrade Filament or use the two-argument form:

     ->hintIcon('heroicon-o-question-mark-circle', 'Custom tooltip');
     

4. Required Attributes:

   • Publishing the config (php artisan vendor:publish --tag="filament-translator-config") lets you toggle which attributes (e.g., placeholder, tooltip) are required vs. optional.
   • Example:

     'required' => [
         'tooltip' => true, // Now tooltips are mandatory
     ],
     

Debugging Tips

1. Check Generated Keys:

   • Use dd(TranslatorPlugin::get()->resolveKey('filament.resources.post.pages.create.label')) to inspect resolution.

2. Verify Path Aliases:

   • Log aliases during boot:

     TranslatorPlugin::make()
         ->pathAliases(['App\\Livewire' => 'livewire'])
         ->register();
     // Check with: TranslatorPlugin::get()->pathAliases
     

3. Disable Auto-Creation in Production:

   • The createMissingTranslationKeys() feature only runs in local environments by default. Override with:

     TranslatorPlugin::make()->createMissingTranslationKeys(fn () => false);
     

Extension Points

1. Custom Schema Components:

   • Register third-party components in config/filament-translator.php:

     'components' => [
         \App\Filament\Components\CustomField::class => [
             'label' => false,
             'helper_text' => true,
         ],
     ],
     

2. Override Resolution:

   • Use key() to force a specific translation key:

     Text::make('Or')->key('custom.or.content');
     

3. Fallback Behavior:

   • Missing translations fall back to Filament’s defaults. Never break UI by omitting keys entirely.

4. Infolist Scope (Future-Proofing):

   • Avoid relying on InfolistScope until explicitly supported. Use the shared form/infolist context for now.

Performance Notes

• Eager Booting: The package registers resolvers once per request (idempotent). No runtime overhead for unused components.
• Lazy Resolution: Translation keys are resolved only when components render, not during boot.