Technical writers typically write UI (User Interface) terms inline, because writing – software being no exception – flows out word after word, sentence after sentence. We present here a different approach, externalization, that can make writing more agile, consistent across multiple tools, 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 as he types, in the appropriate DITA tags. Depending on the label category, the element can be <uicontrol>, <wintitle> or a series of <uicontrol> tags in a <menucascade>, etc. 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 these terms in a Terminology Base to ensure the mapping between languages:

UI terminology base

When the DITA content is processed in the CAT (Computer-Aided Translation) 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 translator is sure he translates appropriately because of the Terminology Base reference.

Once delivered and published, it will look like:

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

 A more systematic approach : Externalizing UI terms

The tech 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 the user documentation.

UI terminology base w identifier
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 (Computer-Aided Translation) tool, UI labels are not open for translation. They cannot be modified by the translator as all references will be 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 delivered and published, it will look like:
Dans le groupe Cellules de l’onglet Accueil, cliquez sur la flèche en regard 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 tech writers, who no longer need to edit every topic to modify these terms. It also allows to write 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 content. Only a republication to solve all keys 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 regard 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 perfectly 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 tech 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.