Translation Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require disjfa/translation-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   Disjfa\TranslationBundle\DisjfaTranslationBundle::class => ['all' => true],
   

2. Database Setup Run migrations (check src/Resources/migrations/ for schema):

   php artisan migrate  # If using Laravel bridge
   # OR
   php bin/console doctrine:migrations:migrate  # Symfony
   

3. First Use Case

   • Enable dynamic translations in config/packages/disjfa_translation.yaml (Symfony) or .env (Laravel):

     disjfa_translation:
         enabled: true
         table_name: translation_entries
     

   • Use in a controller/view:

     $this->get('translator')->trans('your.key');
     // Dynamic updates will persist to DB on save.
     

Implementation Patterns

Core Workflow

1. Translation Overrides

   • Users edit translations via UI (e.g., admin panel). The bundle intercepts changes and stores them in the translation_entries table.
   • Example: Override a default translation for a specific locale:

     $translator = $this->get('translator');
     $translator->setLocale('en');
     $translator->trans('welcome.message', ['%name%' => 'John']);
     // Save override to DB (triggered by UI action).
     

2. Layered Translation Loading

   • The bundle merges:
     1. Default translations (from translations/ or YAML/JSON files).
     2. Database overrides (user-edited entries).
   • Priority: Database entries override files.

3. Integration with Forms

   • Use in Symfony forms or Laravel form requests to allow in-situ translation edits:

     // Symfony Form Type
     $builder->add('translation_key', TextType::class, [
         'attr' => ['data-translation-bundle' => true],
     ]);
     

4. Caching Strategy

   • Disable Symfony’s default translation cache (framework.translation.cache_warmer = false) to ensure real-time DB updates.
   • Laravel: Clear cache after DB updates:

     Cache::forget('translations');
     

Gotchas and Tips

Pitfalls

1. Cache Invalidation

   • Issue: Translations may not update immediately if Symfony’s cache is enabled.
   • Fix: Disable cache warming or manually clear cache after DB updates:

     php bin/console cache:clear
     

2. Locale-Specific Overrides

   • Issue: Overrides apply globally unless scoped by locale. Ensure setLocale() is called before edits.
   • Fix: Add a locale column to the translation_entries table if granularity is needed.

3. Migration Conflicts

   • Issue: Schema conflicts if using custom translation tables.
   • Fix: Override table_name in config or extend the migration class.

4. Performance

   • Issue: Heavy DB queries if many overrides exist.
   • Fix: Add indexes to translation_entries(key, locale) and limit queries with WHERE locale = ?.

Debugging Tips

• Log Missing Keys: Enable Symfony’s translation.logger to track unresolved keys:

  framework:
      translation:
          logging: true
  

• Check DB Entries: Verify overrides exist in translation_entries:

  SELECT * FROM translation_entries WHERE key = 'your.key';
  

Extension Points

1. Custom Storage

   • Extend Disjfa\TranslationBundle\Storage\TranslationStorageInterface to support Redis or API-backed overrides.

2. Event Listeners

   • Hook into disjfa_translation.pre_save to validate or transform translations before DB storage.

3. UI Integration

   • Use the data-translation-bundle attribute to auto-link form fields to translation keys (requires JS):

     $('[data-translation-bundle]').on('change', function() {
         const key = $(this).data('key'); // Implement key extraction logic
         // Send to backend via AJAX.
     });
     

4. Fallback Logic

   • Override Disjfa\TranslationBundle\Loader\TranslationLoader to add fallback locales dynamically:

     public function load($locale, $domain = null) {
         $translations = parent::load($locale, $domain);
         if (empty($translations)) {
             $translations = $this->load('en', $domain); // Fallback to English
         }
         return $translations;
     }