Next: Chapter 8  Building Online Courses Up: Part I  User's Guide Previous: Chapter 6  Index, Glossary and Bibliography

Chapter 7
Version Management and Localization

This chapter discusses how the RichDoc Framework supports version management of a document, in Section 7.1. Section 7.2 describes how the RichDoc Framework supports the management of localized versions of a master document.

7.1 Version Management

Under Construction

7.2 Managing of Localized Documents

Under Construction

Often you need to write a document, and provide localized versions of that document. It is also common that the master document is updated several times in its lifetime, and you would like to update the localized subversions accordingly. The RichDoc Framework's Localized Versions Management (LVM) greatly facilitates these tasks.

When you finish authoring of certain version of your document, and you want to create a localized version of it, use Tools → Create Localized Document command. A new document is created, which is initially a mere copy of the master document. When you open the newly created document, all paragraphs are displayed with blue background, indicating that they need translation. When you place text cursor into that paragraph, a localization window shows up. The localization window displays the difference between two master versions that needs to be accommodated into the localized document, see Figure 7.1a.

Figure 7.1 States of Localization Paragraphs: (a) Created, (b) Up-to-date, (c) Modified

Initially, the whole master paragraph is displayed in blue color, indicating that new material has been added and needs to be translated. When you finish your translation, press the Commit button to confirm that the translation corresponds to the current version of the master document. The correspondence is indicated by normal white background of the paragraph and normal black text color in localization window, see Figure 7.1b. When you later modify the master document and update the localized document, all paragraphs in the localized document needing revision are displayed with purple background. If you put the text cursor into that paragraph, the localization window shows the change that has been done in the master since last translation, see Figure 7.1c. When you finish the revision of the translation, press the Commit button to confirm that the paragraph corresponds to the current version of the master again.

Figure 7.2 Localized Document Life Cycle

The life cycle of the documents is summarized in Figure 7.2. First, you must create the master document, and develop it for some time. When you create the localized document, you have two independent documents that can be modified independently, perhaps by different persons. When you finish some version of the master document, you may update the localized document by invoking the Create Localized Slave again, and then revise the localized document by modifying localized paragraphs that have been modified in the master document. Of course, you may create and manage many localized documents for different languages.

Note that the Editor supports only the master-slave scenario. That is, if you want to amend a group of localized documents, you should first amend the master version, and then update the localized versions accordingly. You cannot, for example, develop two language versions of a single document in parallel, for example write chapters 1–5 in English and 6–10 in Czech, and later on finish the missing chapters in the other language. You must also decide at the very beginning which language would play the master role.

Note that you may use the Create Localized Document command only once to generate an initial version of the localized document, and then you may change its structure considerably w.r.t the master document. However, if you want to use the automated synchronization system, note that the master and the slave documents must have identical structure, and may only differ in the paragraph texts. It is not possible, for example, to have a section with two paragraphs in the master document, which corresponds to three-paragraph section in the translated document. If you make any structural changes in the translated document, they will get lost upon next synchronization with the master document. This implies that if you delete any material from the master document, the corresponding translated material is deleted from the localized document as well. It is therefore recommended to backup your localized document before it is updated with the master.

7.2.1 Localizing the Index

If your document contains an index, you need to translate it as well. Translating index is quite similar to translating normal document content. If you open the index editor in a localized document, index entries are marked with the same colors as in the document, see Figure 7.3.

Figure 7.3 Index Editor Displaying Localized Index

Up-to-date index entries are displayed with normal, white background. Entries needing translation have blue background, and entries needing revision have purple background. When you translate or revise the index entry, press the Commit button to confirm the translation. Note that line in the document, strict one-to-one correspondence between master and localization index entries is required. You may add or remove index entries to the localized document, but such changes get lost when you update the slave with the master document again.

Note that when localized representation of a paragraph containing index association is added to a localized document, the associations are reconstructed in the localizable copy, and are automatically redirected to the localized index. When you translate the paragraph, you may do it in such a way that the associations are preserved. You are however free to add or remove associations, that is, index associations do not count to the requirement on structural equivalence of the master and the localized document. This also implies, that if you add new index association to a paragraph that has been localized already, that association is not reconstructed upon next localization update, and must be reconstructed manually.

Next: Chapter 8  Building Online Courses Up: Part I  User's Guide Previous: Chapter 6  Index, Glossary and Bibliography