At this time, the contents in different languages in DoX CMS are managed fully independently. For this reason, contents must be prepared accordingly in the source language before they are sent out to be translated. When you do this, there is less need for repeated translation requests for corrections and management purposes.
Do note how changes only to identifiers instead of the content only involve the contents being retrieved from memory instead of being retranslated if you use the same translation service both times. This generally makes the costs of a new translation non-existent.
This piece discusses methods that make it easier to manage translated content in DoX CMS. These methods must be applied before content is translated for them to be effective. Otherwise, the effects can only be generalized if you edit the translated contents or have the contents translated again.
Translate command
Translation requests in DoX CMS require you to use the Translate command. This command is available both in the Editor menu and the Publications menu. We recommend that you primarily use it on ready publications in the Publications menu because additional features ara available for translated publications. You can publish the contents into the translation package and you can lock the revisions related to the translation request to be used in the target language. When you do this, new translation requests involve no changes to the revisions that the publication uses even when that revision of the publication has not been locked with the workflow.
You must use the Translate command because only the XML-based translation files that it generates can be uploaded back to have their contents be deployed automatically. For example, a publication in the DITA format might suit translators equally well but it cannot be uploaded in the system after the translation is ready.
Always make sure what action the system will apply by default to each topic in the translated content both when you make the translation request and when you upload it. When you make a new translation request, the system should add a new revision that corresponds to the revision in the source language to the target language as a marker that its translation is underway. When the translatopns are then uploaded, the contents of these revisions should be replaced with the translated contents. As is discussed in more detail below, there are also situations in which the default action becomes the content being excluded from the translation file, for example.
Attached images
The images that are attached to content must often be adjusted when you either change the image itself or change its dimensions. The methods presented below let you do this without having to repeat said changes in each language.
Localized images

Localized images let you specify a target for attachments where its contents can be managed separately in each language. In this case, the values for links to them need not be updated in each language, when different images are used in different languages. Additionally, this lets you change the linked images easily through the Attachments menu. Otherwise, to change an image, you must either replace the original file with a new file that has the same filename in the same folder or change the links for related image elements in each language. The Edit Localized Image menu lets you simply change the language-specific or default image.
Element classes
The width and height of image elements can be changed directly in the editor. This makes such settings a part of the topic in question. Related changes must be made separately in each language.
If the sizes for images are defined with the help of element classes and these element classes are applied before the contents are translated, the same element classes will be used in each language. As a result, when you adjust the values for the images affected by these element classes, you will simultaneously adjust all the similarly used images across languages. You can adjust images such as the icons in tables that describe different commands or inline icons added with variables like this.
When independent pictures, where you will not use their settings elsewhere, are involved, you can use the ID values of the elements in which they are embedded instead. Image elements themselves cannot have ID values. However, they are always embedded in paragraphs (p) and paragraphs (as well as fig elements and section elements) can have ID values. In this case, you can use a selector like ‘#ID img’ or variations thereof to manage the image through your style sheet. Replace ‘ID’ with the ID value of the element in which the image is embedded. This method also requires that the ID values were added to the elements in the source language before any translation requests. Otherwise, you must either add them separately in each language or make a new translation request with these contents.
Workflow
Content must have suitable formulations and identifiers before it is deployed. Pieces of content should only be sent to be translated when they have been verified to be deployable. Otherwise, each subsequent change will require a new translation to transfer the changes to other languages as well. The effects of this are multiplied by the number of required languages. Proper use of the workflow helps ensure that content is ready to be translated.
Review
It is important to review as part of the translation process both before the translation request and after the translations are ready. We recommend that you use the Approval state of the workflow and the associated Review menu to do this. You review content primarily to make sure that the content is ready before you lock it by approving it. This lets you check the effects of otherwise hard to observe details such as the effects of the style sheet, the results of filtering content, and link functionality. We also recommend that you publish drafts of PDF files to check how their page layout looks.
You must also review the translations that you receive. There are too many details that you may need to adjust even when you cannot understand the language itself. Such details include
- Variables: Even though the positions for variables’ values are identified as not to be translated, they are a part of the translation file. As a result, translators can accidentally translate them, in which case those variables cannot retrieve their proper values. It is also possible that some of the required complex variables or publishing variables had not been included in the translation file. They should be located as a result. The default value for untranslated complex variables is ‘-‘.
- Tables: Regardless of the layout that you use for columns, differences between languages can break them. An expression that is too long and continuous makes automatic layouts for tables spread over page limits. With a fixes layout, such expressions will themselves extend past column lines. As such, you should always review tables in translated publications.
- Note elements: We recommend that you add titles that specify their types to note elements through the style sheet. As is discussed in more detail below, you must account for style sheets as part of the translation process. If the style sheets are not updated accordingly, such parts of the document will remain in the original language or not show at all in the translated version. The same principle applies to other elements implemented in this way.
- Titles: Translation files have two positions for titles in each topic. The first value shows on the list menu and the other is used in the content itself when it is published. The title for the list menu updates to match the actual title of the topic when the content is saved. This quirk in the translation file can be missed by the translators, and they can only translate one of the values or translate them in different ways as a result. You should thus check the titles when you review translated content.
Approval
You must use the Approval state of the workflow to approve of content to be translated before you send it out. By default, this state locks the content because it can no longer be reserved for editing. This can be changed in the settings for workflow states but we recommend against doing so.
When content is sent to be translated in DoX CMS, the system checks each content revision for whether they have already been included in translation requests for the that language. If the same revision has been part of an earlier translation request for that language, the system will exclude it from the new translation file as the defalt action for it. This avoids redundant retranslations of of the same content when, for example, only a different part of a publication has been updated.
When you use the Approved state to prevent content from being edited, you thus ensure that a new revision is necessary before changes can be made to a topic. This lets the topic be included in new translation files once more. In turn, this allows the changes to its contents to be transferred to other languages through the translation process.
Tags
The primary means to transfer the tags for elements in topics in particular across languages involves translation requests. This means that the tags for content should be ready, too, before you include it in a translation request. Doing so avoids the need for a separate translation request to update the tags in the target language later.
Variables
DoX CMS lets you add the values for complex variables as part of any translation request. For you to do the same with publishing variables that have different values in different languages, you must make the translation request through the Publications menu. The publishing variable in question must be set to have language-specific values in the Edit Publication menu when you edit its value.
When translation files are uploaded to the system, the values for included variables are deployed accordingly. If variables are not added to translation files, they will show with their default values in publications. This default value involves the lack of a language-specific value. If variables are included in the translation file but translators fail to translate them, their values will match the source language.
You can also use complex variables for values that are not used directly in the content. They cannot be directly included in style sheets because of the order in which content is processed. Style sheets, on the other hand, cannot be directly added to translation files and updated when they are uploaded in the system. Doing this lets such values be translated as part of a translation request from DoX CMS, though, and they can then be copied to style sheets. More details on this are provided below.
Line breaks
Do not use forced line breaks (Shift + Enter) in DoX CMS. Translation files are in XML. They do not recognize the presence of forced line breaks and will just exclude them even though the editor lets you add them. This means that the translated content will not show the line break and that the content in question will be translated as one block.
Style sheet
Style sheets let you use rules tied to specific languages. The detail most commonly handled as a language-specific setting in the style sheet are titles such as ‘Warning’ for note elements. You can also manage details such as the logo shown inside a page header or footer based on a market, if you will not use different styles for different markets and if the markets correspond to sets of languages.
In style sheets, language-specific rules involve the use of the language identifiers in your copy of DoX CMS as part of the associated selectors. If you want there to be a default value which is independent of all languages, it can be added above the language-specific options without a language identifier of its own. This makes the appropriate language-specific selector overtake the default rule when the publication is in that language. You must remember to add the corresponding language-specific values in the style sheet when content is translated to a new language. The correct values for that language can be added to a translation reques as complex variables as is specified above. These values can then be copied from the language-specific field for that variable in the editor foe variables after said translations are uploaded in the system.
The example below shows how the title ‘Warning’ before a note element with that type can be shown in either Finnish or in English depending on the language of the publication. This example does not demonstrate other details about such implementation because there are numerous available implementations.
[lang="en"] [data-ditaatribute-type="warning"]:before {content: 'Warning';}
[lang="fi"] [data-ditaatribute-type="warning"]:before {content: 'Varoitus';}
Summary
Since content in different languages must be managed independently in each language except when translation files are uploaded in the system, the content in the original language must be fully ready before it is sent to be translated. The best way to do this is to review and lock the content with the workflow and the related review feature. You must also account for language-specific values outside the translation file such as the titles for note elements if they are added through the style sheet. Users must add values like this themselves because the system only processes content related to the translation file when it is uploaded in the system.
You should use localized images to help manage them in the future even when said image attachments do not require different images for different languages. This lets you change these images without replacing the original files and without changing the link addresses in each language. You can use the style sheet to control image sizes with the help of element classes, for example. If you use the editor to determine image dimensions, you must do it separately in each language.
You can add both publishing variables with language-specific values and complex variables in translation files. Complex variables can be used like this for parts that would otherwise not be included in a translation file such as language-specific values in style sheets. Even though uploading the translation file in the system does not deploy these values where they will be used, you can still have translated values as part of the translation file. These values need to then just be copied to their actual positions once the translation file has been uploaded in the system.