Translation management
Daisy can keep track of the translation status of documents which exist in multiple language variants.
Summary
Each document has a reference language variant, in which the original content is written. Other language variants are kept in sync with this reference language variant. For this purpose, versions have a 'synced-with' attribute which points to the {language-variant, version} with which they are in sync. Since not all versions might contain changes which invalidate the translations, it is possible to indicate a version contains only minor changes.
The reference language
The reference language variant is the variant in which the original content is written. The reference language variant is a property of a document, in other words it can be different for each document (but not for branches within the same document). The reference language variant of a document can be changed at any time.
In Daisy, we use the convention that if the reference language variant for a document is set, the document is considered to be under translation management.
In the Daisy Wiki, the reference language can be set by opening the document in the editor, you will find the reference language below the "Misc" tab.
The synced-with link
Each version of a language variant can link to another language variant version with which it is “in-sync”. Being “in-sync” means the content of the language variant corresponds to the content of the other language variant version. The other language variant will normally be the reference language variant.
The synced-with pointer cannot point to non-existing language variants or versions, nor to the same language variant. Circular references are possible, though can't cause harm nor be useful.
The synced-with pointer of a version can be updated after version creation (for the case you would have made an error or forgot to set it).
In the Daisy Wiki, if the reference language for a document is set, the document editor will show GUI elements to set the synced-with value. The synced-with can be modified later on through the version overview screen.
Version change type: major or minor
Each version has a change-type attribute indicating if the version contains major or minor changes. For translation management, a major change means the version contains changes which invalidate the translations based on it. So, changes which might seem minor, like changing the order of two bullets or making a particular word appear in bold, are in fact major if the change must also be performed in translated variants.
The major/minor distinction is, for translation management, only relevant for the reference language (or any other language to which synced-with pointers point).
Example
Let's use an example to illustrate how the use of the reference language, the version change type and the synced-with pointer allows to keep track of translation status.
The table below shows the version history of two language variants of a Daisy document, the reference language "EN" and the translated variant "FR".
Time progresses from top to bottom, in each row either a change to the reference language or the translated variant is shown.
|
Document 1-DSY |
||||||||
|---|---|---|---|---|---|---|---|---|
|
Reference language |
Translated variant |
|||||||
|
Version |
Change type |
State |
last major |
live major |
Version |
Synced-with |
LangInSync() ? |
|
|
V1 |
Major |
Draft |
V1 |
NULL |
(does not exist) |
|||
|
V2 |
Major |
Publish |
V2 |
V2 |
(does not exist) |
|||
|
V1 |
No |
|||||||
|
V2 |
EN:V2 |
Yes |
||||||
|
V3 |
Minor |
Publish |
V2 |
V2 |
Yes |
|||
|
V4 |
Major |
Draft |
V4 |
V2 |
No |
|||
|
V3 |
EN:V4 |
Yes |
||||||
Note that all versions have the same properties available, even though not shown in the table above. That is, the reference language versions also have a synced-with pointer, but it will not be used, and the translated variant has also change type, state, etc., but they are mostly irrelevant for the translation management.
To make the example more concrete, here is what happened, row-by-row:
EN version 1: Ron, who is reponsible for the documentation of his company's new product 'X' creates a document in Daisy. The document is not ready for publication so he saves the document as draft.
EN version 2: Ron continues his work on the document. The document is ready for prime time, so he publishes it.
FR version 1: Jacques is responsible for maintaining the product documentation in French. He is halfway done with his translation, so he saves his document (normally he would save as draft, this is not shown in the table above because it does not matter for translation management).
FR version 2: Jacques finishes his translation of the to document and indicates this by setting the synced-with field.
EN version 3: Ron notices he made a small typo and fixes this. Since his change does not influence what the translations, he marks his change as being a 'minor' change.
EN version 4: Ron starts adding content to his work. His work is not ready for publishing so, again, he saves as draft.
FR version 3: Jacques notices that he needs to update the French translation to reflect the changes Ron made to the English version.
In the last step, one could wish not to translate the document until it is published, for this, you could use the LiveNotInSync('live') condition in the query language.
Querying for translation work
The Daisy query language contains conditions which allow you to query for translated variants which are not up to date with the reference language or with the language variant pointed to by the "synced-with" pointer. See the conditions LangInSync(), LangNotInSync() and the syncedWith identifiers.
Additionally, Daisy comes with a search tool which helps people who are not familiar with the query language query for these documents. The tool is available at http://example.com/path/to/daisy/<site>/translmgmt/search and via the menu under tools -> Translation management.
There are no comments.