I18N Xliff Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cyberspectrum/i18n-xliff
   

   Add to composer.json if not auto-discovered:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Cyberspectrum\\I18nXliff\\": "vendor/cyberspectrum/i18n-xliff/src/"
       }
   }
   

   Run composer dump-autoload.

2. Basic Usage Load translations from an XLIFF file:

   use Cyberspectrum\I18nXliff\Xliff;
   
   $xliff = new Xliff();
   $translations = $xliff->loadFromFile('path/to/translations.xliff');
   

3. First Use Case: Export Laravel Lang Files Convert Laravel's resources/lang to XLIFF for translators:

   $xliff = new Xliff();
   $xliff->exportToFile('resources/lang/en', 'translations.xliff');
   

Implementation Patterns

Workflow: Translation Pipeline

1. Extract Strings Scan Laravel views/controllers for __() or trans() calls:

   $xliff->extractStringsFromDirectory('app/Http/Controllers', 'translations.xliff');
   

2. Merge Updates Re-import XLIFF back into Laravel’s lang files:

   $xliff->importToDirectory('translations.xliff', 'resources/lang/en');
   

3. Pluralization Support Handle plural keys (e.g., messages.{0,1,2}):

   $xliff->setPluralizationRules(['en' => 'one', 'es' => 'two']);
   

Integration Tips

• Laravel Service Provider Bind the XLIFF class for dependency injection:

  $this->app->singleton(Xliff::class, function ($app) {
      return new Xliff(config('i18n-xliff.default_locale'));
  });
  

• Artisan Command Create a custom command for CLI workflows:

  use Cyberspectrum\I18nXliff\Xliff;
  
  class ExportTranslationsCommand extends Command {
      protected $signature = 'i18n:export {locale}';
      public function handle(Xliff $xliff) {
          $xliff->exportToFile("resources/lang/{$this->argument('locale')}", 'xliff/translations.xliff');
      }
  }
  

• Middleware for Dynamic Locale Use middleware to switch locales dynamically:

  public function handle($request, Closure $next) {
      $xliff = app(Xliff::class);
      $xliff->setLocale($request->locale);
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions XLIFF files may merge keys incorrectly if namespaces (e.g., validation.required) aren’t preserved. Use setNamespace():

   $xliff->setNamespace('validation');
   

2. Encoding Issues Ensure XLIFF files use UTF-8 encoding. Force encoding when reading:

   $xliff->loadFromFile('file.xliff', 'UTF-8');
   

3. Pluralization Rules Default rules may not match all languages. Override globally:

   $xliff->setPluralizationRules([
       'en' => 'nplurals=2; plural=(n != 1);',
       'fr' => 'nplurals=2; plural=(n > 1);'
   ]);
   

Debugging

• Validate XLIFF Structure Use validateXliff() to check for malformed files:

  if (!$xliff->validateXliff('file.xliff')) {
      throw new \RuntimeException('Invalid XLIFF structure');
  }
  

• Log Missing Keys Enable debug mode to log untranslated keys:

  $xliff->setDebug(true);
  $translations = $xliff->loadFromFile('file.xliff');
  // Check debug logs for missing entries
  

Extension Points

1. Custom Translator Adapters Extend Cyberspectrum\I18nXliff\Translator\AbstractTranslator to support non-Laravel systems:

   class MyTranslator extends AbstractTranslator {
       public function get($key, $locale) {
           return $this->data[$locale][$key] ?? $key;
       }
   }
   

2. Hooks for Pre/Post Processing Use events to modify translations before/after import:

   $xliff->on('beforeImport', function ($data) {
       // Sanitize or transform data
   });
   

3. Git Integration Automate XLIFF updates in CI/CD by diffing files:

   git diff --name-only | grep '\.xliff$' | xargs -I {} php artisan i18n:update {}