Lokalise Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Lokalise Integration: The bundle is designed specifically for Symfony applications, leveraging Lokalise’s API/webhook system to automate translation file synchronization. This aligns well with PHP-based Symfony projects requiring i18n workflows.
• Translation Workflow: The bundle bridges Lokalise’s cloud-based translation platform with local Symfony translation files (e.g., app/Resources/translations), enabling a seamless pull/push mechanism for JSON/YAML/PO files.
• Limitation: Only supports Symfony 2.x/3.x (last release in 2018), which may conflict with modern Symfony 5/6+ or Laravel ecosystems. The package is not Laravel-native and requires Symfony’s kernel/bundle system.

Integration Feasibility

• Lokalise API Dependency: Requires a paid Lokalise account (API token/project ID) and proper webhook configuration. No native Laravel support means additional abstraction layers (e.g., Symfony bridge) may be needed.
• File Structure: Supports customizable paths for web (web/locales) and Symfony (app/Resources/translations) locales, but assumes a Symfony-specific directory structure. Laravel’s resources/lang or public/locales would need mapping.
• Format Support: Primarily JSON (configurable), but Laravel typically uses PHP arrays or JSON for translations. Conversion logic may be required.

Technical Risk

• Deprecation Risk: Last release in 2018 (5+ years old). No active maintenance, compatibility unknown with:
  • Symfony 5/6+ (deprecated AppKernel, new DI container).
  • Laravel’s service container or routing system.
  • Modern PHP (8.x) or composer dependencies (e.g., ext-zip/ext-curl may need updates).
• Security: Hardcoded API tokens in config.yml (no environment variable support) and lack of recent vulnerability scans.
• Functional Gaps:
  • No native Laravel event listeners or service providers.
  • CLI command (lokalise:import) won’t work without Symfony’s console component.
  • Webhook routing requires Symfony’s annotation-based controllers.

Key Questions

1. Symfony vs. Laravel Compatibility:
   • Can this bundle be adapted to Laravel via a Symfony bridge (e.g., symfony/http-client, symfony/console)?
   • Would a custom Laravel service (e.g., LokaliseTranslationService) be more maintainable?
2. Translation Format Handling:
   • How will Laravel’s resources/lang (PHP arrays) map to Lokalise’s JSON/PO exports?
   • Are there tools (e.g., laravel-translation-manager) to pre/post-process files?
3. Webhook Integration:
   • Can Laravel’s Route::post() handle the webhook instead of Symfony’s annotation routing?
   • How will the bundle’s AlicornLokaliseBundle be initialized in Laravel’s AppServiceProvider?
4. Maintenance Overhead:
   • Will forks/updates be required to support PHP 8.x or Laravel’s ecosystem?
   • Are there alternatives (e.g., crowdin/crowdin-api, poeditor/poeditor-api) with better Laravel support?
5. Error Handling:
   • How will failed webhook payloads or API errors be logged/retried?
   • Does the bundle support rollback mechanisms for corrupted translations?

Integration Approach

Stack Fit

• Symfony Projects: Ideal for existing Symfony 2/3 apps using Lokalise. Minimal changes required (bundle enablement, config).
• Laravel Projects: Not natively compatible. Integration would require:
  • Option 1: Symfony Bridge
    • Use symfony/http-client to call Lokalise API directly.
    • Replicate webhook logic in Laravel’s Route::post() with a custom controller.
    • Example:

      // app/Http/Controllers/LokaliseWebhookController.php
      use Symfony\Component\HttpClient\HttpClient;
      
      public function handleWebhook(Request $request) {
          $client = HttpClient::create();
          // Process $request->getContent() and sync files to storage/app/public/locales
      }
      

  • Option 2: Custom Laravel Service
    • Build a LokaliseService class using Guzzle for API calls and Laravel’s filesystem for local storage.
    • Example:

      // app/Services/LokaliseService.php
      class LokaliseService {
          public function fetchTranslations(string $apiToken, string $projectId) {
              $response = Http::withHeaders([
                  'Authorization' => 'Bearer ' . $apiToken,
              ])->get("https://api.lokalise.com/api2/projects/{$projectId}/exports");
              // Save to storage_path('app/translations/...');
          }
      }
      

  • Option 3: Fork & Adapt
    • Modify the bundle to work with Laravel’s ServiceProvider and RouteServiceProvider.
    • High risk due to outdated codebase.

Migration Path

1. Assessment Phase:
   • Audit current translation workflow (e.g., manual uploads, Crowdin, etc.).
   • Test Lokalise API/webhook functionality with a proof-of-concept (Symfony bridge or custom service).
2. Pilot Integration:
   • For Laravel: Implement a minimal viable webhook handler (e.g., POST /lokalise/webhook) using Guzzle.
   • Replace Symfony’s config.yml with Laravel’s .env for API tokens.
3. Full Rollout:
   • Automate translation sync via Laravel’s scheduler (e.g., php artisan lokalise:sync).
   • Integrate with Laravel’s translation loader (e.g., FileLoader for resources/lang).

Compatibility

Sequencing

1. Phase 1: API Access
   • Set up Lokalise project and API token.
   • Test API calls using Postman/cURL.
2. Phase 2: Webhook Setup
   • Configure Lokalise webhook to point to Laravel’s endpoint (e.g., https://app.com/lokalise/webhook).
   • Implement a temporary Symfony bridge or custom controller to validate payloads.
3. Phase 3: File Sync
   • Write logic to extract Lokalise’s ZIP to storage/app/public/locales.
   • Convert formats if needed (e.g., JSON → PHP arrays).
4. Phase 4: Laravel Integration
   • Publish translations to resources/lang using Laravel’s FileLoader.
   • Add error handling/logging (e.g., Laravel’s Log facade).
5. Phase 5: Automation
   • Schedule periodic syncs (e.g., php artisan lokalise:sync --daily).
   • Set up health checks for webhook failures.

Operational Impact

Maintenance

• Symfony Projects:
  • Low maintenance if Lokalise API remains stable. Updates may break due to bundle age.
  • Risk of deprecated Symfony components (e.g., AppKernel, YAML config).
• Laravel Projects:
  • High maintenance overhead due to lack of native support.
  • Custom code will require:
    • Regular testing of API/webhook changes.
    • Updates for Laravel/Symfony version conflicts.
  • Alternative: Consider Laravel-specific packages (e.g., spatie/laravel-translation-loader) for future-proofing.

Support

• Symfony:
  • Limited support due to inactivity. Issues may require manual debugging.
  • Community resources are scarce (2 stars, no dependents).
• Laravel:
  • No official support; relies on custom implementation.
  • Debugging may involve:
    • Laravel’s service container vs. Symfony’s DI.
    • Webhook payload validation (e.g., signature checks).
  • Recommendation: Engage Lokalise support for API/webhook documentation.

Scaling

• Performance:
  • Webhook payloads may be large (ZIP files). Laravel’s default server (e.g., Valet/Forge) may struggle with concurrent requests.
  • Mitigation:
    • Use queue workers (laravel-queue) for async processing