Keyrefs and conrefs are one very powerful way how DITA can achieve higher levels of reuse and manage more product variations in an automated way.

Essentially, a keyref or conref is a placeholder that is filled dynamically with relevant content at the time of publication. The benefit is that the same document with small variations can be produced in an automated fashion. For example, a keyref or conref can be used to identify a product name or version number that might change frequently based on a request by marketing, or as the consequence of a new release.

Careful analysis of your documentation quickly reveals several types of potential candidates for keyrefs or conrefs, including product names, user interface strings, sequences of user interface strings, numerical values, graphics, and type designators.

Note: UI strings are often a special case, as a different organization or agency may handle the translation process, and your team will need to make sure that you use the same source strings for translation that are used in the software. This is important because the UI strings in the software and documentation can get out of sync.

Keyrefs and conrefs can present a challenge in the localization process if not handled properly:

• In the ideal case, translators can see the content that will be reused in a conref or keyref; but often the process does not support this.
• The content pulled into the topic by the conref or keyref needs to make sense on its own terms, after it has been translated.
• Sometimes content that is in a conref or keyref may not need to be translated at all, such as product names which may remain the same in source and target languages.

Tip: Try to conref complete thoughts

If a writer has applied a conref to small elements (such as <ph> or other smaller XML elements), the translated material might not be grammatically correct when the translated conref element is populated in the sentence at publish time. In many languages, there must be agreement between nouns, adjectives, and verbs, in gender and tense, as well as a differentiation of plural and singular. For some languages such as Japanese, there must be subject-article agreement.

For this reason, instruct your writers to be cautious in their use of the conref. Use the conref only to reference complete thoughts that can stand on their own, such as Notes, Tables, Sections, or complete sentences. These content blocks can be translated independently and will not cause translation problems when they are pulled into other contexts during the publishing process.

Tip: Do not keyref or conref nouns or adjectives inside sentences

Many languages need different case endings for the noun, verb, adjective or adverb, depending upon the location in the sentence.

For example, if you keyref or conref a single word such as “none,” “blue,” or “first,” the translator may not know how to translate the term.

In Spanish, the word “first” can be conveyed by the words “primero,” “primera,” “primer,” “primeros,” and “primeras,” depending on the gender, whether the noun is singular or plural, and the sentence structure.

In many languages, the gender of the noun requires agreement with other words in the sentence. For example, in French the noun’s gender determines the conjugation of the verb in the sentence. If the noun is not known to the translator, he or she cannot safely determine the gender of the verb.

<p><ph conref=“some noun”/> has been added to the list</p>

When this English sentence is translated into French, the translator does not know how to translate the sentence. Depending upon the gender of the noun, which is not known because it is in the conref, the translation should either be

<p><ph conref=”noun”/> a été ajouté à la liste</p> [assuming a masculine noun]

-OR-

<p><ph conref=”noun”/> a été ajoutée à la liste</p> [assuming a feminine noun]

The gender of the noun in some languages also determines the gender of the article that precedes the noun. For instance, in French and German, nouns can be masculine, feminine, or neutral. In the following example, the use of a noun referenced by a conref makes it impossible for the translator to determine how the article “the” should be translated. In French the words le, la, or l’ designate gender of the article; In German, der, die or das indicate the gender of the article.

<p>The <ph conref=”noun”/> will start when you log in.</p>

When this sentence is translated into German, the translator cannot determine how to translate the article “the” before the conref. Depending upon the gender of the noun, populated later, the translation of the article can be either Der, Die or Das:

<p>Der <ph conref=“noun“/> wird gestartet, wenn Sie sich anmelden.</p>
<p>Die <ph conref=“noun“/> wird gestartet, wenn Sie sich anmelden.</p>
<p>Das <ph conref=“noun“/> wird gestartet, wenn Sie sich anmelden.</p>

Tip: Use only keyref or conref nouns when you know the context very well

If you know the context very well, you can use a keyref or conref to reference nouns used in product names or terms.

This capability is extremely important for agile companies. For example, software strings of your product might change until the last day before the product is released to market. If software strings change, you may want to update the strings in a single location, rather than going through all individual topics to apply the change.

Caution: Use inserted text only when the text is self-contained and does not affect its surrounding context.

<p>Press the <uicontrol conkeyref=“buttons/ok-button”/> button</p>