Eggs'n'Cereal

A basic, generic PHP XLIFF serialization library.

Installation

The recommended way to install Eggs'n'Cereal is of course to use Composer:

{
  "require": {
    "tableau-mkt/eggs-n-cereal": "@dev"
  }
}

Note: There is no stable release, necessarily. So...

Usage

The basic idea of this library is that you provide a series of "translatable" classes for your entities. These "translatable" classes implement the EggsCereal\Interfaces\TranslatableInterface interface.

A TranslatableInterface instance is meant to wrap your entity with a unified method to get and set data. You must do so by implementing:

• TranslatableInterface::getData()
• TranslatableInterface::setData()

In addition to getting and setting data, you must also provide a way to get a unique identifier for your translatable entity, as well as a label by implementing:

• TranslatableInterface::getIdentifier()
• TranslatableInterface::getLabel()

The identifier and label are used to validate an XLIFF file during the import / unserialization process.

Once you've implemented the interface, you can serialize and unserialize your translatable like so:

// Generated by composer.
require_once('vendor/autoload.php');

// Instantiate your translatable here.
$yourTranslatable = new YourTranslatable(/*...*/);

// Instantiate the serializer:
$xliffSerializer = new EggsCereal\Serializer();
$targetLanguage = 'pt-br';

// Serialize your translatable like so:
$xlf = $xliffSerializer->serialize($yourTranslatable, $targetLanguage);

// Unserialize an xliff file like so:
$translatedFile = file_get_contents('/path/to/translated-pt-br.xlf');
$xliffSerializer->unserialize($yourTranslatable, $targetLanguage, $translatedFile);

Sample implementation

Suppose you want to translate data stored in a flat, single-level PHP array. You might write an ArrayTranslatable class like so:

use EggsCereal\Interfaces\TranslatableInterface;

class ArrayTranslatable implements TranslatableInterface {

  public $data = array();

  public function __construct(array $data) {
    $this->data = $data;
  }

  /**
   * {@inheritdoc}
   */
  public function getData() {
    $response = array();

    // Iterate through each item in the array.
    foreach ($data as $key => $value) {
      // For each item, set a #label and #text value.
      $response[$key] = array(
        '#label' => $key,
        '#text' => $value,
      );
    }

    return $response;
  }

  /**
   * {@inheritdoc}
   */
  public function setData(array $data, $targetLanguage) {
    foreach ($data as $key => $value) {
      $this->data[$key] = $value['#text'],
    }
  }

  // Note, you'll also need implementations for getIdentifier() and getLabel().
}

With this ArrayTranslatable implementation, usage is straightforward.

$xliffSerializer = new EggsCereal\Serializer();
$targetLang = 'fr-fr';

$arrayTranslatable = new ArrayTranslatable(array(
  'foo' => 'Translatable foo value',
  'bar' => 'Translatable bar value',
));

// Generate an XLIFF file from your translatable.
$xlf = $xliffSerializer->serialize($arrayTranslatable, $targetLang);

// Import a translated XLIFF file.
$translatedFile = file_get_contents('/path/to/translated-array-fr-fr.xlf');
$xliffSerializer->unserialize($translatable, $targetLang, $translatedFile);

// Now, your array will be translated and might be available like so:
print_r($arrayTranslatable->data);
array(
  'foo' => 'Valeur de foo traduisible',
  'bar' => 'Valeur de bar traduisible',
);

Forewarning

This library is a work in progress and draws heavily from work by Cloudwords on their Cloudwords for Multilingual Drupal module.

Use at your own risk, for now.