[DITA Loc Wire series] 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 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:
| EN | FR |
|---|---|
| Home | Accueil |
| Cells | Cellules |
| Insert | Insérer |
| Insert Cells | Insérer les cellules |
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.
| Unique ID | EN | FR |
|---|---|---|
| UI_HOME | Home | Accueil |
| UI_CELL_CELLGROUP | Cells | Cellules |
| UI_INSERT_CELLGROUP | Insert | Insérer |
| UI_INSERTCELL_CELLGROUP | Insert Cells | Insérer les cellules |
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 editable by the translator. All the 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% frozen, especially with the agile information development methodology, 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 allows writing the user documentation before the software is fully designed and validated. Similarly, you can perform the translation of the documentation without waiting for the software localization to be fully tested. In addition, updates to the translated UIs are automatically mirrored in the documentation without any additional translation. They do 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>.If it is not reproduced in the resource file, this 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.
