Over the last weeks, Dan, Brian and myself worked on adding translation capabilities to Doctrine PHPCR-ODM. PHPCR-ODM is an object – document mapper for the php content repository ( PHPCR). Thanks to the Liip Ecostar process, we got funding to do this during work time.

How does it work?

Using persistTranslation($document, $locale) or persist($document) with the @Locale annotation allows to store several copies of the “same” document in different languages. You update the document for the next language and then persist that translation too. Using find() to get a translated document, the LocaleChooserStrategy class will find the best (according to its implementation – might look at session locale, browser preferences, user account settings, …) available translation for a document. And using findTranslation() you can explicitly specify which language you want.

There are two translation strategies available: Store translated fields in a separate namespace as properties of the same node, and namespaced child nodes per locale with the translated properties in them. You can add your own strategies with the DocumentManager::addTranslationStrategy() method. Translation always happens on a document level, not on individual fields to keep performance reasonable.

Our translation strategies use a namespace to avoid collisions with other attributes resp. child nodes. In order to use multilanguage, set up the console and run

php bin/phpcr doctrine:phpcr:register-system-node-types

.

When using findTranslation, the existing document instance is updated rather than a new one created. Otherwise we could get into non-deterministic situations when you update non-translated fields on two objects.

A complete example how using the translations looks like, using the default configured LocaleChooser:

use DoctrineODMPHPCRMappingAnnotations as PHPCRODM;

/**
 * @PHPCRODMDocument(alias="translation_article", translator="attribute")
 */
class Article
{
    /** @PHPCRODMId */
    public $id;

    /**
     * The language this document currently is in
     * @PHPCRODMLocale
     */
    public $locale = 'en';

    /**
     * Untranslated property
     * @PHPCRODMDate
     */
    public $publishDate;

    /**
     * Translated property
     * @PHPCRODMString(translated=true)
     */
    public $topic;

    /**
     * Language specific image
     * @PHPCRODMBinary(translated=true)
     */
    public $image;
}


$localePrefs = array(
    'en' => array('en', 'fr'),
    'fr' => array('fr', 'en'),
);

$dm = new DoctrineODMPHPCRDocumentManager($session, $config);
$dm->setLocaleChooserStrategy(new LocaleChooser($localePrefs, 'en'));

// then to use translations:

$doc = new Article();
$doc->id = '/my_test_node';
$doc->publishedDate = new DateTime();
$doc->topic = 'An interesting subject';
$doc->image = fopen('english.jpg');

// Persist the document in English
$this->dm->persistTranslation($this->doc, 'en');

// Change the content and persist the document in French
$this->doc->topic = 'Un sujet intéressant';
$doc->image = fopen('english.jpg');
$this->dm->persistTranslation($this->doc, 'fr');

// Flush to write the changes to the phpcr backend
$this->dm->flush();

// Get the document in default language (English if you bootstrapped as in the example)
$doc = $this->dm->find('DoctrineTestsModelsTranslationArticle', '/my_test_node');
echo $doc->topic;

// Get the document in French (updates the existing document)
$this->dm->find('DoctrineTestsModelsTranslationArticle', '/my_test_node', 'fr');
echo $doc->topic;

What was added?

The complete overview is in the pull request. Just a summary:

  • New annotation options:
    • translator=attribute|child|your_own is a new attribute for the @Document annotation, to mark a document as being translated and specify how translations are to be stored
    • @Locale makes a class property hold the locale the document is currently translated to.
    • translated=true is a new attribute for all properties to mark the String, Number, Binary and so on as being translated.
  • TranslationStrategy is used for the translator attribute of the document. Default strategies for attribute and child exist.
  • LocaleChooserStrategy is used to determine what language matches best for doing language fallback, with the possibility to do language fallbacks based on your self defined logic. The default strategy is configurable with an ordered list of locales per requested locale
  • DocumentManager::persistTranslation($document, $locale) save document in that language
  • DocumentManager::findTranslation($className, $id, $locale) load a document in the specified locale (instead of the default one)
  • DocumentManager::getLocalesFor($document) (get the list of locales this document currently exists in)