Translation Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require cwd/translation-admin-bundle
   

   Register the bundle in config/app.php under providers:

   CWD\TranslationAdminBundle\CWDTranslationAdminBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CWD\TranslationAdminBundle\CWDTranslationAdminBundle" --tag="config"
   

   Update config/cwd_translation_admin.php with your database connection and locale settings.

3. First Use Case Create a translation model (e.g., app/Models/Translation.php):

   use CWD\TranslationAdminBundle\Model\Translation as BaseTranslation;
   
   class Translation extends BaseTranslation
   {
       protected $table = 'translations';
   }
   

   Run migrations:

   php artisan migrate
   

   Access the admin interface at /admin/translations (ensure CWD\TranslationAdminBundle\Admin\TranslationAdmin is registered in config/cwd_translation_admin.php).

Implementation Patterns

Workflow: Managing Translations

1. CRUD Operations Use the built-in admin controller to manage translations via a Symfony-like admin interface. Customize routes in config/cwd_translation_admin.php:

   'admin' => [
       'route_prefix' => 'admin',
       'translations' => [
           'route' => 'translations',
           'controller' => CWD\TranslationAdminBundle\Admin\TranslationAdmin::class,
       ],
   ],
   

2. Integration with Laravel Ecosystem

   • Service Providers: Extend functionality by binding services in AppServiceProvider:

     public function register()
     {
         $this->app->bind(
             CWD\TranslationAdminBundle\Service\TranslationService::class,
             App\Services\CustomTranslationService::class
         );
     }
     

   • Events: Listen to translation events (e.g., TranslationCreated) in EventServiceProvider:

     protected $listen = [
         'CWD\TranslationAdminBundle\Event\TranslationCreated' => [
             App\Listeners\LogTranslation::class,
         ],
     ];
     

3. Localization Workflow

   • Sync translations with Laravel’s lang directory:

     use CWD\TranslationAdminBundle\Service\TranslationExporter;
     
     $exporter = new TranslationExporter();
     $exporter->exportToLanguageFiles(storage_path('lang'));
     

   • Import translations from JSON/CSV:

     $importer = new TranslationImporter();
     $importer->importFromJson(file_get_contents('path/to/translations.json'));
     

4. API Access Expose translations via Laravel API routes:

   Route::middleware('auth:api')->get('/api/translations/{locale}', [TranslationController::class, 'getByLocale']);
   

   Use the bundle’s TranslationRepository to fetch data:

   $translations = app(\CWD\TranslationAdminBundle\Repository\TranslationRepository::class)->findByLocale('en');
   

Gotchas and Tips

Pitfalls

1. Database Schema Conflicts

   • The bundle assumes a default schema. If extending, ensure your Translation model’s $fillable matches the bundle’s expectations:

     protected $fillable = ['locale', 'key', 'value', 'context', 'description'];
     

   • Fix: Override migrations or use Schema::table() to add custom columns.

2. Locale Handling

   • The bundle defaults to en if no locale is specified. Explicitly set locales in config:

     'locales' => ['en', 'de', 'fr'],
     

   • Tip: Use Laravel’s App::setLocale() to dynamically switch locales in the admin panel.

3. Caching Issues

   • Translations may not update immediately if cached. Clear the cache after bulk updates:

     php artisan cache:clear
     php artisan view:clear
     

4. Admin Route Conflicts

   • The /admin prefix may clash with other admin packages (e.g., spatie/laravel-permission).
   • Solution: Rename the prefix in config:

     'admin' => [
         'route_prefix' => 'i18n',
     ],
     

Debugging Tips

1. Log Translation Events Enable debug mode in config/cwd_translation_admin.php:

   'debug' => env('APP_DEBUG', false),
   

   Check logs for event dispatching issues:

   tail -f storage/logs/laravel.log | grep "TranslationEvent"
   

2. Validate JSON/CSV Imports Use the bundle’s validator before importing:

   use CWD\TranslationAdminBundle\Validator\TranslationValidator;
   
   $validator = new TranslationValidator();
   if ($validator->validateJson($jsonData)) {
       $importer->importFromJson($jsonData);
   }
   

3. Override Admin Templates Copy the default Twig templates from vendor/cwd/translation-admin-bundle/Resources/views to resources/views/admin/cwd/translation_admin to customize the UI without modifying the bundle.

Extension Points

1. Custom Fields Add custom fields to the Translation model and extend the admin form:

   // app/Admin/TranslationAdminExtension.php
   namespace App\Admin;
   
   use CWD\TranslationAdminBundle\Admin\TranslationAdmin as BaseAdmin;
   
   class TranslationAdminExtension extends BaseAdmin
   {
       public function configureFields(string $pageName): array
       {
           $fields = parent::configureFields($pageName);
           $fields[] = 'custom_field';
           return $fields;
       }
   }
   

   Register the extension in config/cwd_translation_admin.php:

   'admin_extensions' => [
       CWD\TranslationAdminBundle\Admin\TranslationAdmin::class => App\Admin\TranslationAdminExtension::class,
   ],
   

2. Translation Sources Extend the TranslationSource interface to pull translations from external APIs:

   namespace App\Services;
   
   use CWD\TranslationAdminBundle\Model\TranslationSourceInterface;
   
   class GoogleTranslateSource implements TranslationSourceInterface
   {
       public function fetch(string $key, string $locale): string
       {
           // Custom logic to fetch from Google Translate API
       }
   }
   

   Bind the service in AppServiceProvider and configure in config/cwd_translation_admin.php:

   'translation_sources' => [
       'google' => App\Services\GoogleTranslateSource::class,
   ],