Provide a multilingual content mechanism

====================
Multilingual Content
====================

Use cases
---------

• Users can create documents that are translations of other documents, only
  for documents that support this feature.

• Available translation languages can be configured by document type or
  configured for the whole application, for every document type supporting
  this feature.

• Distinct documents are used for every translation, as they should be be
  able to follow disctinct review processes, be published independantly,
  have different access rights, etc...

• When a "translatable" document is created, the language field is
  required, but it can be changed afterwards.

• At creation time, translations in other languages may be created
  automatically in the same folder and documents linked. This can be useful
  if the application wants to provide the document in the original version,
  in case nobody took time to translate it.

• The initial document created is considered as the "master".

• It is possible to create a new translation from the master, or from any
  other translation of this initial document.

• There is no restriction on the translation language: the master document
  can have several translations in the same language (is this acceptable?).

• When creating a new translation or editing an existing one, it is possible
  to select the master or another existing translation to display the fields
  to translate on the same form (in view mode only). It is also possible to
  chose to prefill the new document fields with the original values.

• (Improvement): display a field by field diff on display)

• It is not possible to remove a master document if translations are still
  present in the platform (even if current user does not have enough rights
  on them) (Improvement: maybe switch master).

• A flag is available on translation documents. Possible values are:

• not-started
• in-progress
• completed
• outdated

All values can be set manually, editing the document. When a translation
is created automatically from master, it is marked as
"not-started". "outdated" flag is set automatically when master document
is modified. "in progress" and "completed" flags are only set manually.

NB: "automatic" behaviour here is not part of the feature, it has to be
implemented by event listeners => provide events and implement specific
behaviour in listeners.

• Custom code can make queries depending on the current language to select
  only documents translated in this language. This is where automatic
  creation of documents (at initial creation) can also be useful in this
  case: all documents will be available in all the supported languages even
  if translations have not be done yet.

• TODO: need to decide what happens when creating a version of a translation
  => what master document is it the translation of? Current live one in
  workspaces? Same when publishing a translation: is the published doc
  marked as a translation of the workspace live doc?

• TODO: copy/paste: when copy/pasting a master or one of its translations,
  the translation links are lost (is this acceptable?). The new translation
  links will have to be specified manually.

Technical architecture
----------------------

• Documents that can be translated have to hold a specific schema named
  "translation" with given fields:

• translation_flag (string)
• master (boolean)

The language can be stored in the dc:language property.

• A runtime component has to accept configurations stating :

• default languages supported globally
• default languages supported per document type

• translation links are held as relations in the relations graph.

• A translation service needs to have the given API:

• boolean isTranslatable(DocumentModel) => can rely on translation schema
  if it's enough (a Facet if it's not)

• DocumentModel getMasterDocumentModel(DocumentModel) => returns the
  master document model for this doc.

• DocumentModelList getSiblingTranslations(DocumentModel)

• DocumentModel createTranslationDocumentModel(DocumentModel initialDoc,
  String language, boolean prefill)

created a new document model with same type than the intial one.
prefills dc:language field with given value, and prefills all other
schemas from given document model values if prefill is true.

• DocumentModel createTranslationDocument(DocumentModel initialDoc,
  DocumentModel translatedDoc)

creates translatedDoc in the repository, with current document as
parent, and marks translated document as a translation of the initial
one. If the intial document is not a master, its master is resolved and
used.

Fails with TranslationException if:

• given docs are of different types.
• no master document can be found from the initial document.

• an adapter is defined on document model. It caches information about its
  translations (master + other languages).

• XXX need to define another use case for folders (complex prop here?) would
  be disrupting to have different folders => maybe define a translation
  type + configure how it applies to document types (use a facet TranslatableFolder). Maybe dupplicate fields with a prefix _fr, _en to ease querying.

• deleting relations not necessary => can be used to retrieve original translations even if doc in workspace do not exist anymore.

• provide pluggable algorithms to retrieve translations + maybe optimize by dupplicating relation properties (or to add additional info like "this doc in french version 1.4 is translated from spanish 1.3).