Translation extension

Introduction - translation and versioning

Cinnamon offers versioning capabilities as well as a language attribute for all document objects out of the box. So why would you need a translation module? The problem arises from the fact that once you have multiple versions of a document in the original language, and if you wish to translate the latest version, you are left with one problem: what version will the new translation have, if this is the first translation to this language? For example:

A repair manual for an engine exists as an English document in version one, two and three. You now want to create a German translation for a new customer, who happens to own the version two of the engine.  If you just copy the document which contains  version two and change the language of the copy, the new translation will start with version one.

Object tree of one document which exists in several versions without proper translation versioning

English original     German translation
version 1            ---
version 2            translation of v2 with version number 1
version 3            ---

This of course simply will not do. If the translated object receives its own version number, the connection between the source language object and the translation will become confusing. It is no longer possible to match version two of the original document to version 2 of the translation - and the time may come where your customer requests a translation of version one...

The solution is to create an empty translation object for each original document and thus preserve the correct version numbers:

Object tree of one document which exists in several versions with correct translation versioning:

English original    German translation
version 1           [empty object], version 1
version 2           translation of v2, version 2
version 3           [empty object], version 3

This way, the correct version numbers are preserved, and you can add translations of existing versions whenever they are needed. And in case of Cinnamon, this is also taken care of by the translation module for branches of the original content (like version 2.3.4).

How to enable the translation extension

Add the following apiClass-Element to your repository's <apiClasses> in the cinnamon_config.xml:

<apiClass>server.extension.Translation</apiClass>

Reboot the server and from now on the following additional API methods will be available to you:

• createTranslation: creates a full version tree (if necessary) and returns the id of a translation target object.
  
• checkTranslation: checks if an document object has already been translated.
  

For comprehensive API documentation, please check the JavaDoc for the Translation class.