[Post #8 of the DITA Loc Wire series, updated from our Jan 2016 post]   Technical writers typically write UI (User Interface) terms inline, because writing flows out word after word, sentence after sentence. We present here a different approach, externalization, that can make writing more agile, consistent across multiple platforms, collaborative and keyword-rich. In this article, we present both and the benefits you can gain from opting for the second one.

The traditional approach: Writing UI terms inline

The technical writer adds the software labels while authoring, using the appropriate DITA tags. Depending on the label category, the element can be <uicontrol>, <wintitle> or a series of <uicontrol> tags in a <menucascade>. In the following examples, we are going to use the <uicontrol> tag.

Example:

On the <uicontrol>Home</uicontrol> tab, in the <uicontrol>Cells</uicontrol>group, click the arrow next to <uicontrol>Insert</uicontrol>, and then click <uicontrol>Insert Cells</uicontrol>.

Once published, it will look like:

On the Home tab, in the Cells group, click the arrow next to Insert, and then click Insert Cells.

The Localization Service Provider (LSP) in charge of the translation will include the terms in a terminology base to ensure the source and translated words are mapped:

UI terminology base

When the DITA content is processed in the Computer-Aided Translation (CAT) tool, UI labels are displayed for the translator to read. The UI terms are highlighted since they match terms in the terminology base:

On the {1}Home{2} tab, in the {3}Cells{4} group, click the arrow next to {5} Insert{6}, and then click {8}Insert Cells{9}.

The terminology base reference ensures failsafe translation.

Once delivered and published, it will look like:

Dans le groupe Cellules de l’onglet Accueil, cliquez sur la flèche en vue d’Insérer, puis cliquez sur Insérer les cellules.

A more systematic approach: Externalizing UI terms

The technical writer lists content references in a central repository of UI terms, either using URIs or keys. Tags such as <uicontrol> no longer embed an inline label as illustrated in the first approach, but reference another <uicontrol> using a unique identifier in a resource file that gathers all the software terms.

The file can then be used to generate and update both the software UI and user documentation.

UI terminology base w identifier
Here’s an example using keys:

On the <uicontrol conkeyref="UI_FILE/UI_HOME"/> tab, in the <uicontrol conkeyref="UI_FILE/UI_CELL_CELLGROUP"/> group, click the arrow next to <uicontrol conkeyref="UI_FILE/UI_INSERT_CELLGROUP"/>, and then click <uicontrol conkeyref="UI_FILE/UI_INSERTCELL_CELLGROUP"/>.

Once published, it will look like:
On the Home tab, in the Cells group, click the arrow next to Insert, and then click Insert Cells.

When the DITA content is processed in the CAT tool, UI labels are not open for translation. They cannot be modified by the translator as all references are processed automatically during the publication process:
On the {1} tab, in the {2} group, click the arrow next to {3}, and then click {4}.

Once published, it will look like:
Dans le groupe Cellules de l’onglet Accueil, cliquez sur la flèche en vue de Insérer, puis cliquez sur Insérer les cellules.

Pros and cons of externalizing UI terms

Pros

  • When software is not 100% stable, centralizing all software terms in one place is safer and avoids generating extra workload for the technical writers, who no longer need to edit every topic to modify these terms. It also allows writing the user documentation before the software is fully designed and validated.
    In addition to this, updates to the translated UIs are automatically reflected in the documentation without any additional translation and does not require a new version of the content. Only a republication to solve all key references is required.
    This is especially true if the documentation refers to a third party or to software that is not yet localized.
  • If you have conflicting UI terms: in our example, the UI term “Insert” is used twice and is not translated the same way:

On the Insert tab--> Sous l’onglet Insertion
Click the arrow next to Insert --> Cliquez sur la flèche en vue d’Insérer

  •  When you do not have an automated source QA tool

A spelling mistake in the source,  even a simple one such as an extra space in the tag:  <uicontrol>Insert␣␣Cells</uicontrol> instead of <uicontrol>Insert␣Cells</uicontrol> that is not reproduced in the resource file leads to practically identical published output. However, it generates a localization issue since the string no longer matches the term.

Cons

  • As shown above, when the rest of the translated string depends on the UI term, the second approach may lead to grammatical errors — e.g. “de Insérer” instead of “d’Insérer” — since the translator cannot anticipate what the string will be.
    While this can be a serious issue when dealing with variables (the UI term can be singular, plural and/or masculine, feminine), it is adapted to UI terms that are neutral and do not interfere with the rest of the sentence.
  • The translator might be missing context if he is not provided with a fully contextual preview.

 Conclusion

We are in favor of externalizing software terms since it ensures consistency between the UI and the user documentation. Plus, it reduces the volume of file processing in the CCMS, as the technical writer no longer needs to edit each topic containing a UI term update (hundreds of topics can be involved). Time-to-market can thus be drastically reduced.