Filament Translations Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require tomatophp/filament-translations
   

2. Run the installation command:

   php artisan filament-translations:install
   

3. Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   $panel->plugin(\TomatoPHP\FilamentTranslations\FilamentTranslationsPlugin::make());
   

4. Publish assets (optional, for customization):

   php artisan vendor:publish --tag="filament-translations-views"
   php artisan vendor:publish --tag="filament-translations-lang"
   php artisan vendor:publish --tag="filament-translations-migrations"
   

First Use Case: Scanning for Translations

• Navigate to the Translations Manager in Filament.
• Click "Scan for New Languages" to automatically detect trans(), __(), and other translation keys in your PHP files.
• Review and edit translations directly in the UI.

Implementation Patterns

Core Workflow: Managing Translations

1. Scanning and Importing:

   • Use the "Scan for New Languages" button to detect missing translations.
   • Import translations via the "Import" button (supports Excel files).
   • Run via CLI for automation:

     php artisan filament-translations:import
     

   • Configure queue-based scanning in config/filament-translations.php:

     'use_queue_on_scan' => true,
     

2. Editing Translations:

   • Edit translations directly in the Filament UI (supports bulk updates).
   • Use the "Export" button to download translations in Excel format.

3. Customizing the UI:

   • Extend the resource with custom columns, actions, or filters using hooks:

     use TomatoPHP\FilamentTranslations\Filament\Resources\Translations\Table\TranslationTable;
     
     public function boot()
     {
         TranslationTable::register([
             \Filament\Tables\Columns\TextColumn::make('custom_column'),
         ]);
     }
     

   • Override the default resource entirely:

     'translation_resource' => App\Filament\Resources\CustomTranslationResource::class,
     

4. Permissions and Access Control:

   • Use Filament’s built-in gates or policies to restrict access to translation management.
   • Example: Hide the "Clear All" button for non-admin users:

     $panel->plugin(\TomatoPHP\FilamentTranslations\FilamentTranslationsPlugin::make()->allowClearTranslations(false));
     

5. Integration with Translation Services:

   • Use extensions like Filament ChatGPT Auto Translation or Google Translations for AI-powered translations.
   • Example:

     $panel->plugin(\TomatoPHP\FilamentTranslations\FilamentTranslationsPlugin::make()->useGptTranslation());
     

Gotchas and Tips

Common Pitfalls

1. Missing Translations After Scan:

   • Ensure spatie/laravel-translation-loader is installed and configured.
   • Verify the scan_paths in config/filament-translations.php includes your project’s directories:

     'scan_paths' => [
         app_path('Lang'),
         resource_path('lang'),
     ],
     

2. UI Not Appearing:

   • Run composer dump-autoload after installation.
   • Check if the plugin is registered in AdminPanelProvider.
   • Ensure Filament is properly bootstrapped (e.g., no middleware conflicts).

3. Performance Issues with Large Translation Sets:

   • Enable queue-based scanning to avoid timeouts:

     'use_queue_on_scan' => true,
     

   • Optimize database indexes for the translations table.

4. Custom Excel Imports/Exports Not Working:

   • Ensure your custom class extends Maatwebsite\Excel\Concerns\ToModel or FromCollection.
   • Verify the config path is correct:

     'path_to_custom_excel_import' => App\Imports\CustomTranslationImport::class,
     

5. Translation Keys Not Detected:

   • The scanner only processes .php files by default (since v4.0.1).
   • For other file types, extend the scanner or use a custom import command.

Debugging Tips

• Log Scanning Results: Enable debug mode in config/filament-translations.php:

  'debug' => true,
  

  Check logs for scanned keys and errors.

• Clear Cache: After customizing hooks or resources, run:

  php artisan optimize:clear
  php artisan view:clear
  

• Verify Database Structure: Publish migrations and run:

  php artisan migrate
  

Advanced Customization

1. Dynamic Navigation Grouping: Override the navigation label/group in config:

   'navigation_group' => 'Localization',
   'navigation_icon' => 'heroicon-o-globe-alt',
   

2. Conditional UI Elements: Use Filament’s visibility rules to show/hide buttons based on user roles:

   \Filament\Tables\Actions\Action::make('clear_all')
       ->visible(fn () => auth()->user()->isAdmin()),
   

3. Extending the Scanner: Create a custom scanner by extending TomatoPHP\FilamentTranslations\Services\TranslationScanner and update the config:

   'scanner_class' => App\Services\CustomTranslationScanner::class,
   

4. Localization of the Plugin Itself: Publish and translate the plugin’s language files:

   php artisan vendor:publish --tag="filament-translations-lang"
   

   Add translations to resources/lang/{locale}/filament-translations.php.

Pro Tips

• Automate Workflows: Use Laravel’s scheduling to run scans periodically:

  // app/Console/Kernel.php
  $schedule->command('filament-translations:import')->daily();
  

• Backup Translations: Export translations regularly via the "Export" button and store backups in version control.

• Collaborative Translations: Combine with Filament Spatie Media Library to attach translation files to entries.

• Fallback Logic: Configure fallback locales in config/app.php to ensure translations always resolve:

  'fallback_locales' => ['en'],
  

```markdown