[Post 18 of the DITA Loc Wire series] Icons are remarkable: they’re universal, they grab the reader’s attention, they’re short and sweet. For all those reasons, they are widely used in documentation. How do you optimize them for DITA and localization?

SEO and accessibility require Alt text

We’ll use the following example to illustrate the process:

To change the time zone of your Windows 10 computer, first click on the Windows icon in your taskbar then the settings icon and click on time and language in the menu.

In DITA you would write:

<p> To change the time zone of your Windows 10 computer, first click on the Windows icon <image href="windows_icon.png"/> in your taskbar then the settings icon <image href="settings_icon.png"/> and click on Time and language in the menu.</p>

Your documentation should also comply with the SEO and accessibility guidelines (we’ll address these topics in a future post). They require that images be associated with an Alt text that can be read by search engine crawlers and screen readers for visually impaired readers.

In DITA you would then write :

<p> To change the time zone of your Windows 10 computer, first click on the Windows icon  <image href="windows_icon.png"><alt>Windows icon in the taskbar</alt></image> in your taskbar then the settings icon <image href="settings_icon.png"><alt>settings icon in the windows menu from the taskbar</alt></image> and click on Time and language in the menu.</p>

The Alt text obstructs localization

Your sentence is ready for localization. The translation tool filters and segments the text string. You have two options:

Segmenting on the Alt tag

This is what standard XML filters do. Your sentence is divided into five segments, whereas three would suffice. Although some translation workbenches allow segment merging, they won’t function here because of the tags.
1 – To change the time zone of your Windows 10 computer, first click on the Windows icon {1}*
2 – Windows icon in the taskbar
3 – in your taskbar then the settings icon {1}
4 – settings icon in the windows menu from the taskbar
5 – and click on Time and language in the menu

* the TMS adds this symbol to indicate the presence of a tag.

No segmenting on the Alt tag

Your sentence will consist of one single segment, which does not make sense and will be impossible to leverage for reuse.
1 – To change the time zone of your Windows 10 computer, first click on the Windows icon {1}{2}Windows icon in the taskbar{3){4} in your taskbar then the settings icon {5}{6}settings icon in the windows menu from the taskbar{7}{8}  and then Time and language in the menu.

Conref to the rescue!

Neither of the above options is truly satisfactory. Here’s what we recommend to ensure consistency and efficient translation:

  1. Create a conref file containing the icons and their corresponding Alt Text.
  2. Conref these icons into the sentence.

When you export the text for localization, whether you filter or not on the Alt tag, the text is divided into three segments. The resulting segments are easy to understand and translate.

In the conref file:

1 – Windows icon in the taskbar
2 – Settings icon in the windows menu from the taskbar
3 – time and language in the menu

In the DITA file:

1 – To change the time zone of your Windows 10 computer, first click on the Windows icon {1} in your taskbar then the settings icon {2}  and then Time and language in the menu.

As a conclusion, the use of conrefs with inline icons ensures the text is understood by the translator and can be leveraged in the translation memory for future reuse.