Translation Manager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kenepa/translation-manager
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="Kenepa\TranslationManager\TranslationManagerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Kenepa\TranslationManager\TranslationManagerServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Kenepa\TranslationManager\TranslationManagerPlugin::make(),
           ]);
   }
   

3. First Use Case

   • Access the plugin via Filament’s sidebar (default path: /admin/translation-manager).
   • Upload a JSON/CSV translation file (e.g., resources/lang/en/messages.json) to import strings.
   • Edit translations directly in the UI, with real-time preview for selected locales.

Implementation Patterns

Core Workflows

1. Translation Management

   • Bulk Import/Export: Use the UI to import from existing JSON/CSV files or export to update local files.
   • Locale-Specific Editing: Edit translations per locale (e.g., en, es) with a side-by-side comparison view.
   • Key-Grouping: Organize translations by namespace (e.g., auth, validation) using Filament’s table grouping.

2. Integration with Laravel

   • Dynamic Loading: Override default behavior to load translations from a custom path:

     // config/translation-manager.php
     'paths' => [
         resource_path('lang/custom'),
     ],
     

   • Event Hooks: Listen for translation updates via events:

     TranslationManager::updated(function (Translation $translation) {
         // Sync with external API or log changes
     });
     

3. Previewing in Context

   • Use the "Preview" tab to see translations rendered in a mock UI (e.g., buttons, forms) for QA.
   • Customize the preview template by extending the PreviewComponent:

     use Kenepa\TranslationManager\Components\PreviewComponent;
     
     class CustomPreviewComponent extends PreviewComponent
     {
         protected function getPreviewTemplate(): string
         {
             return view('filament.translation-manager.preview.custom');
         }
     }
     

4. Syncing with Git

   • Automate commits/pushes post-edits via a post-update hook:

     // app/Providers/AppServiceProvider.php
     public function boot()
     {
         TranslationManager::updated(function () {
             Artisan::call('git', ['add', 'resources/lang']);
             Artisan::call('git', ['commit', '-m', 'Update translations']);
             Artisan::call('git', ['push']);
         });
     }
     

Gotchas and Tips

Common Pitfalls

1. Locale File Structure

   • Ensure your resources/lang directory mirrors the expected structure (e.g., en/messages.json). The package expects JSON files by default; CSV requires explicit configuration:

     'csv' => [
         'enabled' => true,
         'delimiter' => ',',
     ],
     

2. Permission Issues

   • Restrict access to sensitive locales (e.g., admin) via Filament’s built-in policies:

     TranslationManagerPlugin::make()->middleware([
         EnsureUserHasAccess::class,
     ]);
     

3. Caching Quirks

   • Clear Laravel’s translation cache after bulk updates:

     php artisan config:clear
     php artisan view:clear
     

   • For Filament’s livewire cache, use:

     php artisan filament:cache-reset
     

4. Namespace Conflicts

   • Avoid duplicate keys across namespaces (e.g., auth.login in both auth.php and messages.json). Use the "Merge" feature to resolve overlaps.

Debugging Tips

• Log Translation Changes Enable debug logging in config/translation-manager.php:

  'debug' => [
      'log_updates' => true,
  ],
  

  Check logs at storage/logs/laravel.log.

• Validate JSON/CSV Use the "Validate" button to catch malformed files before import. For custom formats, extend the TranslationImporter:

  class CustomImporter extends TranslationImporter
  {
      public function import(string $path): array
      {
          // Custom logic (e.g., parse YAML)
          return parent::import($path);
      }
  }
  

Extension Points

1. Custom Fields Override the default text input for translations (e.g., add rich text or tags):

   use Kenepa\TranslationManager\Components\TranslationForm;
   
   class CustomTranslationForm extends TranslationForm
   {
       protected function formSchema(): array
       {
           return [
               Textarea::make('translation')
                   ->rows(5)
                   ->toolbarButtons([
                       'bold', 'italic', 'link',
                   ]),
           ];
       }
   }
   

2. Webhook Notifications Trigger external actions (e.g., Slack alerts) on translation updates:

   TranslationManager::updated(function (Translation $translation) {
       Http::post('https://hooks.slack.com/...', [
           'text' => "Translation updated: {$translation->key}",
       ]);
   });
   

3. Multi-Tenant Support Scope translations to tenants by overriding the Translation model’s boot() method:

   protected static function booted()
   {
       static::addGlobalScope('tenant', function (Builder $builder) {
           $builder->where('tenant_id', tenant()->id);
       });
   }