[post 2 of the DITA Loc Wire series]

DITA is intended to maximize re-use and single sourcing, thus simplifying content maintenance and reducing localization costs.  Two DITA features enable re-use:

  • Conditional content
  • Content inclusion (conref, conkeyref, keyref, etc.)

This post explains how to generate localization-friendly keyrefs – we will talk about conditional content in an upcoming DITA Loc Wire post.

Use keyref as often as possible

Keyref should replace standard text for any expression that may be updated, such as a brand name, a UI term, or a corporate term. There are three benefits to using keyref:

  • Consistent wording across all the content
  • Easy update. If a term needs to be updated, you do it once in the map file, and the update occurs automatically
  • Consistent localization. The map file lists the keyref terms in the source and target languages, so the term is automatically replaced by its proper translation.

Let’s look at this example:

The details can be found in the latest version of the Administration Guide.

Accordingly, a wise technical writer will build the string as follows:

<p>The details can be found in the latest version of the <keyword keyref=”Admin_Guide”/>.</p>

Or since it refers to an external document:

<p>The details can be found in the latest version of the <cite><keyword keyref=”Admin_Guide”/><cite>.</p>

Where the keyref is defined in another topic or map:

<keydef keys="Admin_Guide"><keyword >Administration Guide</keyword></keydef>

Looks perfect, doesn’t it?

Beware: localizing keyrefs can generate gender and case errors

Let’s translate the sentence into French:

<p>Vous trouverez les détails dans la dernière version du <cite><keyword keyref=”Admin_Guide”/><cite>.</p>

Which reads perfectly well:

Vous trouverez les détails dans la dernière version du Manuel Administrateur.

So far, so good ! Now the French term is updated to “Documentation Administrateur”. When published again, the sentence now reads:

Vous trouverez les détails dans la dernière version du Documentation Administrateur.

Which is incorrect, since Documentation is a feminine word; it should be instead:

Vous trouverez les détails dans la dernière version de la Documentation Administrateur.

The update has generated a syntax error, but updates aren’t frequent, so is it a real problem?

And what about German:

<p> Die Details finden Sie in der neuesten Version des <cite><keyword keyref=”Admin_Guide”/><cite>.</p>

Which reads as follows:

Die Details finden Sie in der neuesten Version des Administrationshandbuch.

Here again, the keyref generates a mistake: Administrationshandbuch is in the genitive case and since Buch is neutral an “s” should be added:

Die Details finden Sie in der neuesten Version des Administrationshandbuchs.

Tips to generate localization-friendly keyrefs

Besides French and German, many European languages require that you pay attention to gender and case, so we recommend following these guidelines with content for localization:

  • Use keyref for neutral, non-declinable terms, such as Product names and UI terms
  • Treat them as proper nouns and remove the articles

Ex: Edit the translated content in Augmented Review

instead of

Edit the translated content in the Augmented Review

  • Adapt your content to include Keyref without a case

Ex: The details can be found in the latest version of the document: Administration Guide.