Translation Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require bsll/translation-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Bsll\TranslationBundle\BsllTranslationBundle::class => ['all' => true],
   ];
   

2. Configure Database Run migrations to create the required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. Import Translations Import existing translation files (e.g., YAML, XLIFF) into the database:

   php bin/console bsll:translation:import --file=path/to/translations.yml --domain=messages
   

4. First Use Case Access the GUI at /translation (or your configured route) to edit translations directly in the database.

Where to Look First

• Documentation: Check Resources/doc/index.md for detailed setup and configuration.
• Commands: Run php bin/console list bsll to see available commands (e.g., import, export).
• Routes: Verify the GUI route in config/routes.yaml or routing.yml:

  bsll_translation:
      resource: "@BsllTranslationBundle/Resources/config/routing.yaml"
  

Implementation Patterns

Workflows

1. Initial Setup

   • Start with a single default language (e.g., English) in YAML/XLIFF files.
   • Import translations into the database:

     php bin/console bsll:translation:import --file=translations/en.yml --domain=messages
     

   • Use the GUI to add/override translations for other languages.

2. Editing Translations

   • Navigate to /translation to view/edit translations by domain/language.
   • Changes are saved directly to the database and override file-based translations.

3. Exporting Translations

   • Export database translations back to files for version control or sharing:

     php bin/console bsll:translation:export --domain=messages --output=translations/exported/
     

4. Integration with Translator

   • The bundle overrides Symfony’s translator service with a DatabaseLoader.
   • Ensure your services.yaml includes:

     Symfony\Contracts\Translation\Loader\LoaderInterface: '@bsll_translation.database_loader'
     

Integration Tips

• Custom Domains: Define custom domains in config/packages/bsll_translation.yaml:

  bsll_translation:
      domains:
          - { name: 'validation', path: '%kernel.project_dir%/translations/validation' }
  

• Validation: Use the GUI to validate translations for completeness (e.g., check for missing keys).
• Caching: Clear the translation cache after bulk edits:

  php bin/console cache:clear
  

Gotchas and Tips

Pitfalls

1. Loader Override Conflict

   • If translations appear inconsistent, ensure the DatabaseLoader is prioritized in services.yaml:

     Symfony\Component\Translation\Loader\LoaderInterface: '@bsll_translation.database_loader'
     

   • File-based translations are loaded first, then overridden by database entries.

2. Migration Issues

   • Run migrations after installing the bundle to avoid table creation errors.
   • If migrating an existing project, back up translations before importing.

3. Permission Errors

   • The GUI requires access to the /translation route. Secure it with Symfony’s security system:

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

Debugging

• Missing Translations: Use the GUI’s "Overview" tab to identify untranslated keys.
• Command Errors: Check logs for file path issues (e.g., --file argument in import command).
• Cache Stale Data: Clear cache after manual database edits:

  php bin/console cache:pool:clear cache.translator
  

Extension Points

1. Custom Fields

   • Extend the Translation entity (e.g., add context or priority fields) by overriding the bundle’s migrations.

2. Custom Exporters

   • Implement a custom exporter by extending Bsll\TranslationBundle\Exporter\ExporterInterface and register it in services.

3. Event Listeners

   • Listen for translation events (e.g., translation.updated) to trigger actions like notifications:

     // src/EventListener/TranslationListener.php
     public function onTranslationUpdated(TranslationEvent $event) {
         // Logic here
     }
     

     Register the listener in services.yaml:

     services:
         App\EventListener\TranslationListener:
             tags:
                 - { name: kernel.event_listener, event: translation.updated, method: onTranslationUpdated }
     

Configuration Quirks

• Default Domain: If no domain is specified in commands, the bundle defaults to messages.
• File Formats: Supports YAML, XLIFF, and PHP arrays. Ensure files use UTF-8 encoding to avoid character issues.
• Environment Variables: Configure database credentials in .env (e.g., DATABASE_URL) before running migrations.