In the next series of posts, I will describe a number of best practices to simplify the localization of DITA files. If you ignore these best practices, it can be quite risky and cause significant headaches in the translation process.

Tip: Do not apply conditions to single words or terms; instead apply conditions to a paragraph or sentence

One of the powerful capabilities of DITA is the ability to apply conditions to content so that it will appear in certain contexts and not others. The use of conditions is powerful for tailoring content to different customer personas (such as an administrator vs. a typical user) or to turn on and off features based on the product model being documented. Content relevancy can be turned on and off with the use of conditions, making it easier to create and manage more variations of documentation that are tailored to the interests and needs of the specific audience. 

While using conditional text is a key capability in authoring, it can be a disaster downstream during localization if not used properly. Conditions typically should only be applied to “whole blocks” of content such as a paragraph or a sentence. Conditions should not be applied to a single word or phrase within a sentence, with some exceptions discussed below. Since linguistic structures and rules such as word order, gender agreement and subject/ verb agreement in the target language can differ from the source language, translation mistakes or challenges can appear during publishing if conditions have been applied to just words or phrases.

In the following example, a writer is trying to write a maintenance note that would apply equally to two different situations: a motor that has one bearing and a motor that has more than one bearing. The same recommendation about replacement applies to both situations. The problem however is that the singular and plural of the word “bearing” requires verb/noun agreement in the target language French.

The DITA standard uses the phrase (<ph>) element to identify content for reuse or conditional processing (for example, when part of a paragraph applies to a particular audience). In the following example, the motor for product A has just one bearing. In product B, the motor has more than one bearing. But the maintenance rule is the same in both.

<p><ph product=“A”>The bearings</ph> <ph product= “B”>The bearing</ph> of the motor
must be replaced after 15,000 hours of operation. </p> 

This sentence looks fine in English. However, placing a condition on the subject of the sentence (“bearing” / “bearings”) presents a problem for the translation of the verb (“must be replaced”). In French, the verb must agree in singular or plural with the subject. The two translations would look something like this:

<Les roulements> du moteur doivent être remplacés après 15.000 heures de fonctionnement.

< Le roulement> du moteur doit être remplacé après 15.000 heures de fonctionnement.

As is evident here, there is no way for the translator to translate the verb, “must be replaced,” in a way that works for both the singular “bearing” and plural “bearings.” With the singular subject, the verb should be translated “doit être remplacé” but with the plural subject the verb should be translated “doivent être remplacés.” The problem is that the conditions were applied in a way that only allows for variations on the subject. The proper way to do this would be to apply the conditions at the whole sentence level and not at the word level.