Symfony Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev devture/symfony-translation-bundle
   

   Add to config/bundles.php:

   Devture\Bundle\TranslationBundle\DevtureTranslationBundle::class => ['dev' => true],
   

2. Configure in config/packages/devture_translation.yaml

   devture_translation:
       base_dirs: ['%kernel.project_dir%/translations']
       source_locale: 'en'
       locales: ['en', 'fr', 'es']
       domains: ['messages', 'another-domain']
   

3. First Use Case

   • Access /_translation route in your browser (default path).
   • Log in (if authentication is configured) and start translating JSON files (e.g., messages.en.json → messages.fr.json).

Implementation Patterns

Workflow Integration

1. Translation File Structure Organize translations in translations/ (or custom base_dirs):

   translations/
   ├── messages.en.json
   ├── messages.fr.json
   ├── another-domain.en.json
   └── another-domain.fr.json
   

2. Domain-Specific Workflows

   • Use domains config to scope translations (e.g., messages, validation).
   • Example: Isolate validation errors (validation.en.json) from UI messages.

3. Hash Files for Sync Leverage .hash.json files to detect outdated translations:

   { "key": "source_hash" }
   

   • Automatically marks translations as "untranslated" if source changes.

4. Symfony Integration

   • Use with translator service:

     $this->get('translator')->trans('key', [], 'messages');
     

   • Cache translations via cache:clear or cache:warmup.

5. CI/CD Pipelines

   • Add to deployment checks:

     php bin/console devture:translation:validate
     

   • Enforce translation completeness in tests.

Gotchas and Tips

Pitfalls

1. File Permissions

   • Ensure web server user (e.g., www-data) can write to translations/:

     chmod -R 775 translations/
     

2. Locale Mismatches

   • Verify source_locale matches your .json files (e.g., messages.en.json).
   • Add missing locales to locales config to avoid UI errors.

3. Hash File Conflicts

   • Delete .hash.json files if translations appear "untranslated" unexpectedly:

     rm translations/*.hash.json
     

4. Domain-Specific Issues

   • Exclude non-translatable domains (e.g., twig) from domains config.

Debugging

• Validate Config

  php bin/console debug:config devture_translation
  

• Check Routes

  php bin/console debug:router | grep translation
  

  Default route: /_translation.

Extension Points

1. Custom Templates Override Twig templates in templates/devture_translation/:

   templates/
   └── devture_translation/
       ├── base.html.twig
       └── translation.html.twig
   

2. Authentication Secure the /_translation route via firewall:

   # config/packages/security.yaml
   access_control:
       - { path: ^/_translation, roles: ROLE_TRANSLATOR }
   

3. Event Listeners Extend functionality via events (e.g., post-save hooks):

   // src/EventListener/TranslationListener.php
   public function onTranslationSave(TranslationEvent $event) {
       // Custom logic (e.g., notify Slack)
   }
   

4. Translation Validation Add custom validation rules:

   devture_translation:
       validation_rules:
           messages: ['required', 'min_length:1']