Of late, I have been contacted several times about the details of how translations operate in DoX CMS. ‘Tis the season, I suppose.
It is also understandable that how this part of the system operates would not be overly familiar to most users. For example, I do not myself actively have to interact with said system. As such, being repeatedly contacted on this subject has directed my attention at some details, some of which even surprised me.
The user manual will also include a more detailed description of these details once it updates. The manual will be updated alongside the rest of the system when the UI of the latter undergoes an overhaul including completely redone icons, for example.
Because not all these details are evident, I deemed it best to also write an article on the subject to help users. We have also already planned steps that clarify the process of controlling translations and give users more options to influence the process. In the meantime, it remains important for users to know how the system operates and how it expects users to behave when they manage translations.
Here, I will discuss (1) the effects of starting a new translation project, (2) the relationship between the workflow and translations, (3) the effects of adding revisions to publications on translations, and (4) the current state of the feature to request partial translations.
Initiating Translation Projects
The first rule for translation projects is:
Do not start any translation projects before all the content to be translated has been reviewed as part of a publication and approved!
The underlying reason is very simple: should any fixes or changes be applied to the contents in hindsight, they must be repeated for each already translated version of it. This coers tags, element classes, the references for links and attachments, the widths of columns in tables, and so forth.
The more languages translations involve, the more carefully they must be reviewed before being translated.
Only the tags associated with topics can even in principle be retroactively transferred to translated content without requiring the use of a new translation project. Such a feature is planned but has yet to be implemented.
Translation Projects
When the Translate-button in the Translate-menu is clicked, the system starts a new translation project. If you do not want to start a new translation project, you can review the translation package by clicking the Preview-button to only download it.
All translation projects are shown in the Localization-menu. They cannot be removed. A feature to let users hide them is currently planned, though. It is thus a good idea not to unnecessarily start new translation projects. They allow you to download the translation package again and to inspect which translation have already been uploaded back to the system.
Content Revisions
When you start a translation project, the content of the revisions in the source language is copied to the target language and the affected revisions there are set to the InTranslation state.
Thus, when content is translated to a language for the first time, you must add new revisions for it. Such new revisions in the target language have the same revision number as the active revision in the source language (e.g. 1.03).
If the target language already has revisions, you can overwrite one with the translation. When you do this, the previous version of said revision is replaced with the contents from the source language. As such, doing this is not recommended for updating prior translations. Instead, you can do so when you start a new translation project before the previous translations have been uploaded back, for example. The revision number and workflow state of of the revision to be overwritten will show in the menu. If it is in the InTranslation state, there is a translation for it that has not been yet uploaded.
When translations are uploaded back, you can repeat this choice: you can either add a new revision for the content or overwrite the contents of the active revision, If said revision is in the InTranslation state, it is best to overwrite it because it is presumably a placeholder with the contents from the source language.
Thus, the important lessons related to the subject are (1) that the revision number that starting a translation project generates corresponds to the source language’s revision and (2) that the action that you should choose when starting a translation project can differ from that used when it is uploaded back. The system will recommend the described options by default as a result.
Translations and the Workflow
Controlling translations has an intimate relationship with proper use of the workflow.
The rule stated above ought to already make this evident.
Approving Content
What matters the most is still that any content to be translated has first been reviewed and approved. There are reasons for this besides how correcting errors afterwards is exponentially harder and more laborous than it would be before content is translated.
When a revision for a topic has previously been included in a translation project, new translations projects that would otherwise include it will skip it instead and exclude it from the project as the default option.
As a result, any later changes to the same revisions before attempting to have it translated again can cause the new translation not to include any updates to the topic.
This default option prevents unnecessarily retranslating already translated content.
All related issues can be avoided by first setting the content to be translated in the Approved state.
The Approved state prevents editing content. Thus, if changes must be made to content that is in the Approved state, doing so requires a new revision to be added. This new revision will then be included in translation projects normally unless it is intentionally excluded from them. This allows any changes to be transferred to other languages alongside new translations of the content.
Workflow for Translations
As was stated above, the revisions in the target languaged that are used for a new translation project have their state set to InTranslation. These revisions are reserved to the user that was specified in the Translate-menu. Once translations are uploaded back, these revisions will automatically shift to the Approval state which lets you review them.
The revisions in the source language being reserved like this entails that other users cannot edit these revisions. This avoids situations where any such edits would be overwritten when the translated content was uploaded back.
While the revisions in the target language are still reserved to said user, though, only they can overwrite said content with the translations when they are being uploaded. This process involves their content being edited, after all. Other must instead add new revisions for the translated content. As such, you must account for this detail when you start a translation project. We are also planning to allow the revisions in the target language not to be reserved at all as part of starting a translation project.
When translations are uploaded back, their state changes from InTranslation to Approval. This makes said content available in the Review menu. It is important to review translated content inside publications and to also check the page layout of translated publications by downloading them. The view used for reviewing does not itself show page breaks.
There are several reasons for why translations should be reviewed. Firstly, translators may make various mostakes that even those who do not understand a language can spot. If you have agreed to the use of a specific term, for example, you can check whether a known alternative to it has been used somewhere instead. Secondly, the revisions in the source language may incorporate means of controlling page breaks or tables that break the layout of the translated publication due to differences between languages. Added page breaks and the determining column width automatically are particularly prone to such issues. The third reason relates to the previous two. Translated content can also be approved to help manage it. This involves the use of the Approved state which locks said content, as stated above. Before content is locked like this, you must obviously make sure that there are no obviously required changes to it first.
Revisions of Publications and Translations
It is generally best to start translation projects through the Publications menu. This links them to the selected revisions of publications. The user interface alone does not diretly express all the changes that decisions during the different phases of this process entail, though.
New Revisions of Publications
Publications also have their own workflow and their content can be locked by setting them in either the Approval state or the Approved state. Locking the contents of publications like this is an important means of ensuring that any later deliveries of the same publications remain identical to the originally delivered versions. Doing so does entail that updates to their contents involve adding new revisions to said publications.
A summary of how how adding revisions to publications operates is provided below. Afterwards, I will detail the effects of that protocol.
When a new revisio is added to a publication, it is added in each language simultaneously. The revision in each language is derived from the preceding revision in the same language.
The first implication this has is that users can have confidence in identifying relations between revisions in different languages. All such revisions have the same revision numbers across languages, unlike revisions for content.
The more important implication is that the revisions in different languages are based on preceding revisions in those languages, though.
The prior revisions transmit the properties that were set for them prior to their content being locked to the new revisions derived from them.
The property that has the greatest relevance to users concerns content revisions that may have been locked to be used in a given language.
If the preceding revision of a publication has any content revisions locked in use, they will remain locked in use in the next revision in that language.
Translations having content revisions locked in use like this is a standard operation within the system. To avoid locking content like this, users must remain conscious of this fact.
Locking Content and Translation Projects
When a translation project is started for a revision of a publication, it is possible to use a feature called ‘Select target revisions for publication’. (The name of this feature will be changed to clarify what it does.) The same feature is available once more when translated content is uploaded back.
This feature is active by default both when a translation project for a revision of a publication starts and when translated content for one is uploaded back. Disabling it requires you to toggle it off each time.
When a translation project starts, this feature locks the content revisions in the target language to the revisions that doing so sets to the InTranslation state.
Locking the content revisions in the target language like this ensures that the contents of the revision of the publication in that language will correspond to the translation for the newest revision in the source language when once it is uploaded. This lets any content revisions locked in use to all be updated simultaneously.
Although, it also entails that the revisions of publications in the target languages for translations will have content revisions locked in use. Once a new revision is added to said publication, the revisions in the target languages for translations will include these content revisions that were locked in use in the way described above.
This feature also only affects the content that a translation package contains. If any content is excluded from a translation package because no new revision has been added to said content after it was last translated, for example, said topics will still have the same values as in the publication’s previous revision. If a revision has been locked in use for such content, that topic will not automatically update to use a later new translation of said topic.
When a translation package is uploaded back, this feature locks in use the content revisions to which the contents of the package are added.
This helps ensure that the revision of the publication in the target language will use the correct content revisions. For example, if new revisions were added to topics as part of uploading the translation package, a selection that was made when said content was sent out could not account for it.
The practical implication of this is that having content revisions update to the newest revisions in the target language automatically according to the Default option for them, this option must be applied to them in the preceding revision of the publication. Afterwards, you must avoid locking revisions in use both when you start new translation projects and when you upload translation packages back.
Partial Translations and Generating IDs
Partial translations and the associated feature to add ID values to elements en masse were new additions to DoX CMS in the early 2021 update.
Partial Translations
We noticed issues with the current implementation of this feature that have now been largely addressed and will be resolved in the next update (late 2021). We do not recommend that you use them before then. In addition to addressing such problems, we have planned to further improve the feature by providing support for the XLIFF translation format, for example.
The basic princple for partual translations (called ‘tag-filtered translations’ after the next update) is to allow translation packages to only include elements associated with specific tags from inside topics. This lets you save in terms of translation costs if each affected topic contains swathes of conditioned content, only some of which must be translated to the specified languages.
Requesting partial translations requires that each applicable element in the content to be included has an ID value. This requirement allows these elements to be ordered properly in relation to each other when the translations are uploaded back.
The feature described below which adds ID values to each element in the selected topics was added to help fulfil this requirement.
The current code for uploading partial translations back does not yet allow you to incorporate separate translations where the rest is translated later, though, despite this having been the intended use for requiring comprehensive use of ID values. The main reason relates to inline elements such as phrases, attached images and links to which you may add tags but no ID values. We have found alternative solutions for such cases but these solutions are intended only as temporary fixes.
As such, partial translations must currently be uploaded as separate revisions which are locked in use for the appropriate publications. We will retain the requirement that all suitable elements have ID values because such pre-existing identifiers can be used to combine old content once we implement a solution.
Add ID Values to All Elements
The Generate IDs feature (changed to ‘Add IDs to All Elements’ in the next update) was added to DoX CMS to support partial translations. It can also be used more generally to, for example, swiftly add ID values to already prepared conref source content.
Earlier, we found a bug related to this feature which caused it to also add ID values to elements that do not support them. Apparently, the coder had been relying on a feature of saving content in the editor which corrects such errors. This is also why initial testing failed to catch the bug. If this feature is used on topics in the master topic tree and not inside the text editor, though, the check mentioned above is not applied. This causes issues such as links in said content not working until it is opened in the editor and saved there.
Such issues will be fixed as part of the next update. Until then, you should be very careful about using said feature.
Summary
Getting translations can often be a step where you do not consider how the system operates in advance. Ideally, this article provides sufficient guidance to plan how translations should be managed.
It is important that you start translation projects only after the content in the source language has been reviewed and approved. This reduces the risk of needing to apply changes to translations in hindsight considerably. It also ensures that later changes to content will be included in later translation projects.
When new revisions are added to publications, they are added simultaneously in each language. Such new revisions inherit the properties of preceding revisions in each language. If prior translations have involved locking content revisions as part of either starting translation projects or uploading translations, that must be accounted for in this respect.
Implementing partial translations fully will take more work from us. If it is not necessary to use this feature, the next update will help with that. If you do so, it is crucial to remember to save the different partial translations of the same topics as their own revisions and to lock those in use appropriately. At least for the time being, they cannot be combined.