Multilanguage support for Doctrine PHPCR-ODM

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


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:

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)

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 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.

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 ?

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.