Find solution for explicit localization when using the document manager

[dantleech]

The document manager currently has one localization aware method - findTranslation, which is the localized analogue of find There does not exist an analogue for ``findMany` and the query builder does not support localizing results.

Other methods that could be localized:

• getReferrers
• getReference (?)
• getChildren
• getDocumentsByPhpcrQuery

Repository classes also have methods which could be localized.

Possible solutions

• Do nothing and deprecate findTranslation: The user must change global state by changing the locale of the locale chooser.
• Make the DocumentManager localizable through a localize method which returns a localized clone of the DocumentManager.
• Add explicit translated methods: getTranslatedReferrers, findTranslatedMany
• Add additional, optional, $locale argument to all existing localizable methods.

[dbu]

i don't think adding a $locale to all those methods is particularly elegant, but probably the best of our available options. changing global state sounds weird. the localize method sounds the most elegant, but would need to resort to global state as well, or we add locale parameters everywhere. cloning the DocumentManager seems like a receipie for chaos. duplicating all methods with a Translated variant explodes the interface of the DocumentManager.

[dbu]

do we want to do something about this? contrary to what i said before, i am now not so happy with adding the $locale everywhere.
maybe a localize() that returns a decorator around DocumentManager which changes the global locale and then changes it back after doing the call to the DM is probably the smallest impact on the rest of the code.

or maybe really go with the first variant of only changing locale by changing global state?

what happens with a query result, does it store the locale of the point of execution or resolve it at a later point?