Localise Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cosavostra/localise-bundle
   

   Add the bundle to config/bundles.php:

   CosaVostra\LocaliseBundle\CosaVostraLocaliseBundle::class => ['all' => true],
   

   Set your Localise API key in .env:

   LOCALISE_EXPORT_KEY=your_api_key_here
   

2. First Use Case: Run the import command to fetch translations from Localise.biz:

   php bin/console localise:import
   

   Verify translations are stored in config/translations/ (default path).

Implementation Patterns

Workflows

1. Periodic Sync: Schedule the localise:import command via Symfony’s cron or a task runner (e.g., Laravel’s schedule:run):

   # config/packages/schedule.yaml
   commands:
       localise:import: '@daily 03:00'
   

2. Custom Translation Paths: Override the default output path in config/packages/cosavostra_localise.yaml:

   cosavostra_localise:
       output_dir: '%kernel.project_dir%/resources/lang'
   

3. Selective Language Imports: Filter languages via command arguments:

   php bin/console localise:import --languages=en,fr,es
   

4. Integration with Translation Services: Use the imported translations in Symfony’s translation system:

   $translator->trans('key', [], 'en');
   

Integration Tips

• Laravel Compatibility: For Laravel projects, use the Symfony bridge (symfony/console, symfony/dependency-injection) and alias the command in app/Console/Kernel.php:

  protected function commands()
  {
      $this->load(__DIR__.'/../../vendor/cosavostra/localise-bundle/src/Command');
  }
  

• Validation: Validate translations post-import with a custom command or service:

  php bin/console debug:translation
  

Gotchas and Tips

Pitfalls

1. API Key Security: Ensure LOCALISE_EXPORT_KEY is never committed to version control. Use .env exclusions:

   echo ".env" >> .gitignore
   

   • Debugging: Test the API key manually via Localise.biz’s API docs before relying on the bundle.

2. File Overwrites: The bundle overwrites existing translation files by default. Backup or use a custom path to avoid data loss.

3. Namespace Conflicts: If using Laravel, ensure the bundle’s service container does not clash with Laravel’s translation system. Prefix services or use explicit bindings:

   $this->app->bind('localise.translator', function () { ... });
   

Debugging

• Command Errors: Enable verbose output for troubleshooting:

  php bin/console localise:import --verbose
  

  Common issues:

  • Invalid API key → Check LOCALISE_EXPORT_KEY.
  • Network errors → Verify Localise.biz API availability.

• Translation Keys: If keys are missing, validate the Localise.biz project structure matches your expected format (e.g., namespace.key).

Extension Points

1. Custom Importers: Extend the bundle’s LocaliseImporter service to transform translations before saving:

   // src/Service/LocaliseImporter.php
   public function import(): void
   {
       $translations = $this->fetchTranslations();
       $this->transform($translations); // Custom logic
       $this->save($translations);
   }
   

2. Event Listeners: Listen for post-import events to trigger notifications or updates:

   # config/services.yaml
   services:
       App\EventListener\LocaliseImportListener:
           tags:
               - { name: kernel.event_listener, event: localise.post_import }
   

3. Configuration Overrides: Dynamically set the API key or output path via environment variables or parameters:

   parameters:
       localise.output_dir: '%env(LOCALISE_OUTPUT_DIR)%'