Lokalise Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alicorn/lokalise-bundle
   

   Ensure ext-zip and ext-curl are enabled in your PHP environment.

2. Enable the Bundle Register in config/bundles.php (Symfony 4+):

   Alicorn\LokaliseBundle\AlicornLokaliseBundle::class => ['all' => true],
   

3. Configure Routing Add to config/routes.yaml:

   alicorn_lokalise:
       resource: "@AlicornLokaliseBundle/Controller/"
       type: annotation
       prefix: /lokalise/webhook
   

4. Basic Configuration Set minimal config/packages/alicorn_lokalise.yaml:

   alicorn_lokalise:
       api:
           api_token: "%env(LOKALISE_API_TOKEN)%"
           project_id: "%env(LOKALISE_PROJECT_ID)%"
       web_path: "public/locales"
       symfony_path: "translations"
   

5. First Use Case

   • Configure a webhook in Lokalise (Settings → Webhooks) pointing to your /lokalise/webhook endpoint.
   • Trigger a build in Lokalise to test the webhook. Verify files appear in public/locales and translations/.

Implementation Patterns

Workflows

1. Webhook-Driven Updates

   • Lokalise triggers the webhook on project builds, automatically downloading and extracting translations to configured paths.
   • Symfony Paths: Files are saved in both web_path (e.g., public/locales) and symfony_path (e.g., translations/ for Symfony’s translation system).
   • Format Handling: Supports json, xliff, etc. (configure via type in api).

2. CLI Sync Manually sync translations via:

   php bin/console lokalise:import
   

   Useful for testing or one-off updates without triggering a build.

3. Bundle Structure

   • bundle_structure: Customize file naming with placeholders like %%LANG_ISO%% (e.g., en.json, fr.xliff).
   • directory_prefix: Group files by language (e.g., en/translations.json).

4. Integration with Symfony Translation System

   • Place translations in symfony_path (e.g., translations/messages.en.yaml) to auto-load via Symfony’s translator.
   • Example config/packages/translation.yaml:

     framework:
         translator:
             paths:
                 - '%kernel.project_dir%/translations'
     

5. Environment-Specific Configs Override paths/tokens per environment (e.g., config/packages/dev/alicorn_lokalise.yaml):

   alicorn_lokalise:
       web_path: "%kernel.project_dir%/public/locales/dev"
   

Tips for Daily Use

• Validation: Add a POST /lokalise/webhook/validate endpoint to verify webhook signatures (Lokalise sends a X-Signature header).
• Logging: Enable debug logging for webhook payloads:

  monolog:
      handlers:
          main:
              level: debug
  

• Caching: Clear Symfony’s translation cache after updates:

  php bin/console cache:clear
  

Gotchas and Tips

Pitfalls

1. Webhook Signature Verification

   • The bundle does not validate Lokalise’s webhook signature by default. Add middleware to verify X-Signature:

     // src/EventListener/LokaliseWebhookListener.php
     use Symfony\Component\HttpKernel\Event\RequestEvent;
     
     public function onKernelRequest(RequestEvent $event) {
         $request = $event->getRequest();
         if ($request->getPathInfo() === '/lokalise/webhook') {
             $signature = $request->headers->get('X-Signature');
             // Implement validation logic (e.g., HMAC comparison)
         }
     }
     

2. File Overwrites

   • The bundle unconditionally overwrites files in web_path and symfony_path. Backup critical files or use a pre-update hook.

3. Path Permissions

   • Ensure PHP has write permissions for web_path and symfony_path:

     chmod -R 775 public/locales translations/
     

4. Deprecated Symfony Features

   • The bundle assumes Symfony 3.x (e.g., AppKernel). For Symfony 4/5, use config/bundles.php and adjust routing to YAML/PHP format.

5. API Rate Limits

   • Lokalise’s API has rate limits. Avoid rapid CLI imports (lokalise:import).

Debugging

• Webhook Failures:
  • Check Symfony logs (var/log/dev.log) for Alicorn\LokaliseBundle errors.
  • Test the webhook locally with curl:

    curl -X POST -H "X-Signature: YOUR_SIGNATURE" -F "file=@/tmp/langs.zip" http://localhost/lokalise/webhook
    

• CLI Command Issues:
  • Run with -v for verbose output:

    php bin/console lokalise:import -v
    

  • Verify extract_file (/tmp/langs.zip) is writable.

Extension Points

1. Custom File Processing Override the FileProcessor service to transform files post-download:

   services:
       alicorn_lokalise.file_processor:
           class: App\Service\CustomFileProcessor
           tags: ['alicorn_lokalise.file_processor']
   

   Implement processFile() in your class.

2. Post-Update Hooks Subscribe to the lokalise.post_update event:

   // src/EventListener/TranslationUpdateListener.php
   use Alicorn\LokaliseBundle\Event\PostUpdateEvent;
   
   public function onPostUpdate(PostUpdateEvent $event) {
       // Clear cache, notify Slack, etc.
   }
   

   Register in services.yaml:

   services:
       App\EventListener\TranslationUpdateListener:
           tags:
               - { name: kernel.event_listener, event: lokalise.post_update, method: onPostUpdate }
   

3. Custom API Endpoints Extend the LokaliseController to add endpoints (e.g., for manual file uploads):

   // src/Controller/LokaliseController.php
   use Alicorn\LokaliseBundle\Controller\LokaliseController as BaseController;
   
   class LokaliseController extends BaseController {
       public function customUploadAction() {
           // ...
       }
   }