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.
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")
/** @PHPCRODMId */
* The language this document currently is in
public $locale = 'en';
* Untranslated property
* Translated property
* Language specific 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
// Change the content and persist the document in French
$this->doc->topic = 'Un sujet intéressant';
$doc->image = fopen('english.jpg');
// Flush to write the changes to the phpcr backend
// Get the document in default language (English if you bootstrapped as in the example)
$doc = $this->dm->find('DoctrineTestsModelsTranslationArticle', '/my_test_node');
// Get the document in French (updates the existing document)
$this->dm->find('DoctrineTestsModelsTranslationArticle', '/my_test_node', 'fr');
The complete overview is in the pull request. Just a summary:
Just FYI we have since changed the API slightly.
Instead of “$this->dm->persistTranslation($this->doc, ‘en’)” one now needs to call “$this->dm->bindTranslation($this->doc, ‘en’)”. Note that this method only works on a previously persisted document.
I just tried the odm on a testproject. but i have a really strange problem with translations. if i add a document which has children – and then try to add a translation to the children documents – the translation will not be saved …. (i tried the same with the symfony cmf – same result ) – is it possible that there’s still a bug ?
hi norbert, sure, it is quite possible we have still bugs. some of them we are currently working on:
can you please open an issue on the doctrine phpcr-odm jira (sorry no github issues here) with the details of your code. what calls to phpcr-odm in what order. and how do your documents look, mapping?
if you manage to create a failing test that demoes the problem (if its not exactly the same as https://github.com/doctrine/phpcr-odm/pull/238) then please do a PR for it, that would help a lot to identify the problem.
then to work around the issue for the moment, maybe it helps to flush before you create the children, or to explicitly persist the children as well.