Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require anisimov/translation-bundle
   

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

   Anisimov\TranslationBundle\TranslationBundle::class,
   

2. Database Configuration Publish the migration and config files:

   php artisan vendor:publish --provider="Anisimov\TranslationBundle\TranslationBundle" --tag="migrations"
   php artisan vendor:publish --provider="Anisimov\TranslationBundle\TranslationBundle" --tag="config"
   

   Run the migration:

   php artisan migrate
   

3. First Use Case: Importing Translations Place your translation files (e.g., messages.en.yml, messages.fr.yml) in config/translations/. Import them via CLI:

   php artisan translation:import
   

   Access the GUI at /admin/translations (ensure you have a route for the admin panel).

Implementation Patterns

Workflow: Managing Translations

1. Importing Translations

   • Use php artisan translation:import to load YAML/JSON files into the database.
   • Customize the import command by extending Anisimov\TranslationBundle\Command\ImportCommand:

     // app/Console/Commands/CustomImportCommand.php
     use Anisimov\TranslationBundle\Command\ImportCommand;
     
     class CustomImportCommand extends ImportCommand {
         protected function getTranslationFiles() {
             return [base_path('custom/translations/*.yml')];
         }
     }
     

2. Editing via GUI

   • The bundle provides a CRUD interface for translations at /admin/translations.
   • Customize the admin panel by overriding the Twig templates in resources/views/vendor/translation/.

3. Retrieving Translations in Code

   • Use Laravel’s built-in translation helper:

     __('messages.welcome'); // Falls back to DB if file-based translations are missing
     

   • Fetch translations directly from the database:

     $translations = \App\Models\Translation::where('locale', 'en')->get();
     

4. Integration with LexikTranslationBundle

   • If using Lexik’s original bundle, alias routes/configs to avoid conflicts:

     // config/translation.php
     'bundles' => [
         'anisimov' => true,
         'lexik' => false, // Disable Lexik if using Anisimov's fork
     ],
     

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • The admin panel routes (/admin/translations*) may clash with existing routes. Override them in routes/web.php:

     Route::prefix('custom-translations')->group(function () {
         // Include Anisimov's routes here
     });
     

2. Locale Fallback

   • The bundle does not enforce locale fallbacks. Configure Laravel’s AppServiceProvider:

     public function boot() {
         app()->setLocale(config('app.fallback_locale'));
     }
     

3. Translation Key Collisions

   • If keys conflict between imported files and existing DB entries, the last imported value wins. Use unique keys or validate during import.

4. Performance with Large Datasets

   • Avoid fetching all translations at once. Use pagination in the GUI or lazy-load in code:

     $translations = \App\Models\Translation::where('locale', 'en')->paginate(20);
     

Debugging Tips

1. Check Database Structure

   • Verify the translations table has columns: id, locale, key, value, domain (if used).
   • Run php artisan schema:dump to inspect the schema.

2. Log Import Errors

   • Extend the import command to log skipped/malformed entries:

     protected function processFile($file) {
         try {
             // Import logic
         } catch (\Exception $e) {
             \Log::error("Failed to import $file: " . $e->getMessage());
         }
     }
     

3. Clear Cache After Changes

   • After modifying translations or config, clear Laravel’s cache:

     php artisan cache:clear
     php artisan view:clear
     

Extension Points

1. Custom Translation Models

   • Extend the Translation model to add fields (e.g., priority, author):

     // app/Models/CustomTranslation.php
     class CustomTranslation extends \Anisimov\TranslationBundle\Entity\Translation {
         protected $fillable = ['priority'];
     }
     

   • Update the bundle’s config to use your model.

2. Validation Rules

   • Add validation to the GUI form by overriding the controller:

     // app/Http/Controllers/TranslationController.php
     use Anisimov\TranslationBundle\Controller\TranslationController as BaseController;
     
     class TranslationController extends BaseController {
         public function store(Request $request) {
             $request->validate([
                 'value' => 'required|string|max:255',
             ]);
             return parent::store($request);
         }
     }
     

3. Event Listeners

   • Listen for translation updates to trigger actions (e.g., notify translators):

     // app/Providers/EventServiceProvider.php
     public function boot() {
         \Anisimov\TranslationBundle\Event\TranslationUpdated::class => [
             \App\Listeners\NotifyTranslators::class,
         ];
     }