Xliff Laravel Package

Getting Started

Minimal Steps

1. Installation (updated for 7.3.0):

   composer require elasticms/xliff:^7.3
   

   Add the service provider to config/app.php (unchanged):

   'providers' => [
       Elasticms\Xliff\XliffServiceProvider::class,
   ],
   

2. First Export (new toXliff() method for collections):

   use Elasticms\Xliff\Facades\Xliff;
   
   $posts = Post::where('needs_translation', true)->get();
   $xliffContent = $posts->toXliff('en', 'fr'); // New fluent method
   file_put_contents(storage_path('app/translations.xlf'), $xliffContent);
   

3. First Import (new updateFromXliff() for models):

   $xliff = simplexml_load_file(storage_path('app/translations.xlf'));
   Post::where('locale', 'en')->updateFromXliff($xliff, 'fr'); // New collection method
   

Where to Look First

• Documentation: Updated Official Docs with 7.3.0 API changes.
• Source Code: Focus on:
  • src/Xliff.php (new fluent methods)
  • src/Concerns/HasXliff.php (new model traits)
  • src/Importers/XliffImporter.php (batch processing improvements)
• Tests: Check tests/Unit/CollectionMethodsTest.php for new fluent API examples.

First Use Case (Updated)

Localize a Blog Post with Fluent API:

1. Export translations directly from collection:

   Post::where('locale', 'en')->get()->toXliff('en', 'es')->saveTo(storage_path('app/translations.xlf'));
   

2. Import translations back with batch updates:

   $xliff = simplexml_load_file(storage_path('app/translated.xlf'));
   Post::where('locale', 'en')->updateFromXliff($xliff, 'es');
   

Implementation Patterns

Usage Patterns

1. Model-Based Export/Import (Updated)

New Trait: Use HasXliff for model-level methods:

// app/Models/Post.php
use Elasticms\Xliff\Concerns\HasXliff;

class Post extends Model
{
    use HasXliff;

    // Now supports:
    $post->toXliff('en', 'fr'); // Single model export
    Post::where('locale', 'en')->updateFromXliff($xliff, 'fr'); // Batch import
}

2. HTML Segmentation (Enhanced)

New Option: Fine-grained HTML segmentation control:

$posts->toXliff('en', 'fr', [
    'segment_html' => [
        'tags' => ['p', 'div', 'span'], // Only segment these tags
        'max_length' => 200, // Split long segments
    ],
]);

3. Bulk Operations with Queues (Updated)

New Job Class: Use ExportXliffJob with chunking:

// Export via queue with chunking
Post::where('locale', 'en')->chunk(100, function ($posts) {
    ExportXliffJob::dispatch($posts, 'fr');
});

4. Custom Metadata (Extended)

New Structure: Nested metadata support:

$posts->toXliff('en', 'ja', [
    'metadata' => [
        'project' => [
            'name' => 'MyApp',
            'version' => '1.0',
        ],
        'translator' => 'Acme Corp',
    ],
]);

Integration Tips

Laravel-Specific (Updated)

• Service Container: Bind with new fluent methods:

  $this->app->singleton('xliff', function ($app) {
      return new \Elasticms\Xliff\Xliff($app['config']['xliff']);
  });
  

• Blade Directives: Updated for 7.3.0:

  Blade::directive('translate', function ($expression) {
      return "<?php echo app('xliff')->getTranslation({$expression}, request()->locale); ?>";
  });
  

Database Sync (New)

• Batch Updates: Use updateFromXliff() with pivot tables:

  $translations = PostTranslation::where('locale', 'en')->get();
  $translations->updateFromXliff($xliff, 'fr');
  

API Endpoints (Updated)

• Streaming Responses:

  Route::get('/xliff/export', function () {
      return response($posts->toXliff('en', request('target_locale')), 200)
          ->header('Content-Type', 'application/xml');
  });
  

Testing (New)

• Fluent API Tests:

  $posts = Post::factory()->count(3)->create();
  $xliff = $posts->toXliff('en', 'fr');
  $this->assertStringContainsString('<file', $xliff);
  

• Batch Import Tests:

  $xliff = simplexml_load_string(file_get_contents('tests/fixtures/translation.xlf'));
  Post::where('locale', 'en')->updateFromXliff($xliff, 'fr');
  $this->assertDatabaseHas('posts', ['locale' => 'fr']);
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods (7.3.0):

   • Issue: Xliff::export() and Xliff::import() are deprecated. Use fluent methods instead.
   • Fix: Replace with:

     // Old:
     Xliff::export($posts, 'en', 'fr');
     
     // New:
     $posts->toXliff('en', 'fr');
     

2. XML Memory Limits (Worsened):

   • Issue: 7.3.0's stricter HTML parsing may increase memory usage for complex pages.
   • Fix: Use XMLWriter for large exports:

     $writer = new XMLWriter();
     $writer->openMemory();
     $posts->toXliff('en', 'fr')->saveTo($writer);
     

3. Locale Validation (Stricter):

   • Issue: 7.3.0 enforces locale format (e.g., en_US instead of en).
   • Fix: Normalize locales:

     $locale = strtolower(str_replace('_', '-', $locale));
     

4. Batch Import Conflicts:

   • Issue: updateFromXliff() may overwrite existing translations silently.
   • Fix: Use upsertFromXliff() for safer updates:

     Post::where('locale', 'en')->upsertFromXliff($xliff, 'fr');
     

5. Special Characters (New Handling):

   • Issue: 7.3.0 escapes XML entities more aggressively.
   • Fix: Use html_entity_decode() if needed:

     $cleanValue = html_entity_decode($translation['value'], ENT_QUOTES, 'UTF-8');
     

Debugging

• Validate XLIFF (Updated): Use the new validateXliff() helper:

  if (!Xliff::validateXliff($xliff)) {
      \Log::error('Invalid XLIFF: ' . Xliff::getValidationErrors());
  }
  

• Log Errors (New): Enable debug mode for detailed errors:

  config(['xliff.debug' => true]);
  

• Inspect Segments (Enhanced): Use the new getSegments() method:

  dd($post->toXliff('en', 'fr')->getSegments());
  

Configuration Quirks

• Default Settings (Updated): New defaults in config/xliff.php:

  'default_version' => '2.2',
  'segment_html' => [
      'enabled' => true,
      'tags' => ['p', 'div', 'span', 'h1', 'h2'],
      'max_length' => 150,
  ],
  'locale_format' => 'en_US', // New strict format
  'debug' => env('XLIFT_DEBUG', false), // New debug mode
  

• Migration Guide: Run the config publisher if upgrading:

  php artisan vendor:publish --provider="Elasticms\Xliff\XliffServiceProvider" --tag="config"
  

  Then update config/xliff.php for new options.