Filament Localization Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mominalzaraa/filament-localization
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="MominAlZaraa\FilamentLocalization\FilamentLocalizationServiceProvider" --tag="config"
   php artisan vendor:publish --provider="MominAlZaraa\FilamentLocalization\FilamentLocalizationServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Configure Supported Locales Update config/filament-localization.php:

   'locales' => [
       'en' => 'English',
       'ar' => 'Arabic',
       // Add more as needed
   ],
   

3. First Use Case: Localize a Filament Resource Run the scanner to auto-generate translations:

   php artisan filament-localization:scan
   

   This scans your Filament resources (e.g., app/Filament/Resources/) and generates structured translation files in resources/lang/.

Where to Look First

• Config File: config/filament-localization.php (adjust locales, paths, and behavior).
• Translation Files: resources/lang/{locale}/filament-localization.php (auto-generated).
• Scanner Command: php artisan filament-localization:scan (re-run after adding new resources).
• Middleware: app/Http/Middleware/SetLocale.php (if custom locale logic is needed).

Implementation Patterns

Core Workflow

1. Develop Filament Resources Create a resource (e.g., php artisan make:filament-resource Post). Add translatable strings (e.g., labels, buttons, validation messages) using Filament’s built-in localization helpers:

   Title::make('name')->label(__('filament-localization::resources.posts.fields.name.label'));
   

2. Scan and Generate Translations Run the scanner to extract strings and generate translation files:

   php artisan filament-localization:scan
   

   The scanner respects:

   • Namespace conventions (e.g., filament-localization::resources.posts.fields.name.label).
   • Custom paths defined in the config.

3. Translate Strings Edit the generated files (e.g., resources/lang/ar/filament-localization.php) and add translations:

   return [
       'resources' => [
           'posts' => [
               'fields' => [
                   'name' => [
                       'label' => 'الاسم',
                   ],
               ],
           ],
       ],
   ];
   

4. Integrate Locale Switching Use the provided middleware or Filament’s built-in locale selector:

   // In FilamentPanelProvider
   $panel->middleware([
       SetLocale::class, // Auto-detects or uses session locale
   ]);
   

Advanced Patterns

1. Custom Scanning Paths Extend the scanner to include non-standard paths (e.g., plugins):

   // config/filament-localization.php
   'scan_paths' => [
       app_path('Filament/Resources'),
       base_path('packages/custom-plugin/resources/filament'),
   ],
   

2. Dynamic Translation Keys Use dynamic keys for reusable components:

   // In a Filament component
   __("filament-localization::components.{component_name}.{key}", ['component_name' => 'user-card']);
   

3. Fallback Locales Configure fallback locales in config/filament-localization.php:

   'fallback_locale' => 'en',
   'fallback_locale_hierarchy' => ['en', 'ar'],
   

4. Testing Localization Use the package’s testing helpers in PHPUnit:

   use MominAlZaraa\FilamentLocalization\Facades\FilamentLocalization;
   
   public function test_translations()
   {
       FilamentLocalization::setLocale('ar');
       $this->assertEquals('الاسم', __('filament-localization::resources.posts.fields.name.label'));
   }
   

Integration Tips

• Filament Widgets/Forms: Wrap translatable strings in __() or |trans:

  TextInput::make('bio')->label(__('filament-localization::resources.users.fields.bio.label'));
  

• Blade Templates: Use the same keys in Blade files:

  <x-filament::section.heading>{{ __('filament-localization::resources.posts.heading') }}</x-filament::section.heading>
  

• API Responses: Leverage the package’s translation system for consistent API messages:

  return response()->json(['error' => __('filament-localization::errors.validation')], 422);
  

• Third-Party Packages: Override translations for packages by extending the filament-localization.php file:

  // resources/lang/ar/filament-localization.php
  return [
      'packages' => [
          'spatie-laravel-permission' => [
              'labels' => [
                  'role' => 'دور',
              ],
          ],
      ],
  ];
  

Gotchas and Tips

Common Pitfalls

1. Scanner Not Picking Up New Resources

   • Cause: The scanner only runs on demand (filament-localization:scan). Forgetting to re-run after adding new resources.
   • Fix: Run the scanner after adding/modifying resources:

     php artisan filament-localization:scan --force
     

2. Translation Keys Not Found

   • Cause: Incorrect namespace in __() or missing translation files.
   • Fix:
     • Verify the key matches the generated structure (e.g., filament-localization::resources.posts.fields.name.label).
     • Check if the locale file exists (e.g., resources/lang/ar/filament-localization.php).
     • Use the --debug flag to see scanned keys:

       php artisan filament-localization:scan --debug
       

3. Locale Not Switching

   • Cause: Middleware not registered or session not set.
   • Fix:
     • Ensure SetLocale middleware is added to Filament’s panel:

       $panel->middleware([SetLocale::class]);
       

     • Manually set the locale in tests:

       $this->actingAsUser($user)->withSession(['locale' => 'ar']);
       

4. Overwriting Translations

   • Cause: Running scan overwrites existing translations.
   • Fix: Use --dry-run to preview changes or back up files before scanning.

Debugging Tips

1. Log Scanned Keys Enable debug mode in the config:

   'debug' => true,
   

   Or run:

   php artisan filament-localization:scan --debug
   

2. Check Generated Files Inspect resources/lang/{locale}/filament-localization.php for missing keys. If a key is missing, it wasn’t scanned—re-run the scanner.

3. Verify Middleware Check if SetLocale is applied to Filament’s panel:

   php artisan route:list | grep filament
   

   Ensure the middleware is listed.

4. Fallback Locale Issues If translations are missing, confirm the fallback hierarchy in config/filament-localization.php:

   'fallback_locale_hierarchy' => ['en', 'ar'],
   

Extension Points

1. Custom Scanners Extend the scanner by creating a custom service provider:

   use MominAlZaraa\FilamentLocalization\Scanners\ScannerInterface;
   
   class CustomScanner implements ScannerInterface
   {
       public function scan(): array
       {
           // Custom logic to scan additional paths
           return [];
       }
   }
   

   Register it in config/filament-localization.php:

   'scanners' => [
       \MominAlZaraa\FilamentLocalization\Scanners\ResourceScanner::class,
       App\Scanners\CustomScanner::class,
   ],
   

2. Dynamic Key Generation Override the key generator for dynamic keys:

   // config/filament-localization.php
   'key_generator' => \App\Services\CustomKeyGenerator::class;
   

3. Post-Scan Hooks Add logic after scanning via events:

   // In a service provider
   event(new \MominAlZaraa\FilamentLocalization\Events\ScanCompleted($scannedKeys));
   

4. Custom Translation Loaders Extend the package’s translation loader to support additional sources (e.g., databases):

   use MominAlZaraa\FilamentLocalization\Loaders\TranslationLoaderInterface;
   
   class DatabaseTranslationLoader implements TranslationLoaderInterface
   {
       public function load(string $locale, string $group): array
       {
           // Load from DB
           return [];
       }
   }