I've been involved with driving the architecture of Oracle applications doc and help content for easy translation for many years now, and had a lot of experience with DITA and DocBook XML specialization and exposure to a whole bunch of authoring tools too. For Oracle Fusion Applications, help content is created using DITA-based writing patterns, and to facilitate the creation of new information types we use loose prototyping schemas (again based on DITA) too. Most doc and help translatability generally considerations focus on the information quality aspects, a focus usually driven more by a desire to control the per word translation cost more than any user experience aspects. Nothing wrong with that, but here's a lot more to translatability than "minimalism" and some vague declarations about "less being more", as I outline here. XML-based structured authoring and use of rendering and transformation tools external to that structure is central to much of what follows.
This guidance is intended for anyone in UX prototyping new XML information types, but anyone can use them as part of their content development process too.
- Use XML structure
correctly and consistently. Transformations may need to be developed for
individual language versions. For example, inline XML elements such as guilabel or literal may have different renderings applied by XSL for different languages.
The success of these transformations depends on the correct use of the XML elements,
not on the information written within the elements. Successful single-sourcing solutions depend on respecting the structural integrity of the XML DTD or schema too.
- Check that text
referenced into a topic using DITA conrefs or other sharing mechanisms makes
sense in context of the surrounding information. Avoid referencing in fragments of text, only complete titles,
sentences or paragraphs. Check for pronouns and possessives used across the entire topic or for
any terminology or same words that might have been used in a different context. Ensure the entire topic makes sense when read.
- Avoid using XML
attributes to carry text that needs translation.
- Use text entities
or variables for non-translatable words but not for concatenation of fragments
of text or for translatable phrases (in some languages even product names may
be translated, so check. Avoid using an 's' to make any referenced text or variable plural. Best to avoid translatable entities if you can, frankly).
locale-specific examples in commonly available content. Any such examples
intended for a localization's (in the enterprise applications sense of the word) purposes are fine.
- Avoid screenshots
in nonembedded help, as these cannot be captured easily. Oracle's User Productivity Kit (UPK) is a viable and proven solution for screen-based instruction instead.
- Allow space in
conceptual or diagram graphics for text expansion during translation (30% is
fine for most text, but for short texts of less than 5 characters allow for at least 100% expansion). In some cases, redrawing may still be necessary however, so supply editable
file formats (Visio, for example) and instructions on colors, fonts and
resolution for the binary image file equivalents.
- Avoid embedding
existing binary files (for example, GIF, JPG, or PNG) inside translatable
graphics files. A binary file format cannot be processed or translated, and may
create resizing issues or other localization or cultural issues in the target
- When using sample
data in graphics (for example, data structures, tables, spreadsheets), provide
source files in editable format (Microsoft Word or Excel, but not text files,
for example) so that content can be easily translated too and added to the
translated graphic. Watch out for BiDi issues too. See the Designing Global Graphics in Enterprise Apps blog entry.
- Use a commonly available graphics or design package that supports Unicode fonts and will run on different language versions of the O/S.
- Keep index entries together, and with the target topic. If using DITA-based DTDs or schemas, create them in the prolog element. If using a DocBook-based schema, create index entries in the TopicInfo element or position the entries together at the beginning of a paragraph of text. Avoiding wrapping existing topic text in index entries, create entries explicitly instead.
- Avoid organizing
tables, lists or other content, alphabetically in help topics if there is some
special informational or usability significance to sequence.
- DITA Guide maps,
tables of contents, indices, and glossaries must rely on alphabetical sorting
at application run time or be sorted alphabetically by the authoring
environment's transformation tools (such as XSL or XSL-FO) using the internationalization features of the
schema or DTD (for example, the index-sort-as element in DITA
DTDs, schemas or maps) before publishing. The reading order of content, or the navigation of
topics, must not be hard-coded alphabetically in the source language.
alphabetically ordered multiple index entries within a single XML index
element. Use the index element structure for different levels of index entries
Adding multiple index terms within one index element,
sorting them, and using delimiters like this violates XML structural and
transformation rules. This kind of violation of structural authoring principles does not work for any language, source included.
- Avoid creating
tables or examples of reports or log files using the programlisting or codeblock XML elements (usually transformed to the PRE element in HTML output). When text expands during
translation, the alignment will be destroyed. Translators cannot recreate these
Using programlisting or equivalent code elements in
XML, or PRE in HTML, to format tables like this does not work as translated text expands. The approach is also a violation of structured authoring principles.
- Use search
keyword and index entry synonyms. Translators cannot change number of keywords,
entries, but can translate them for market or leave in English, if appropriate.
Do not remove synonyms on translation grounds.
- When developing recorded UPK demos, provide
international customers with instructions on how to create their own versions.
Translated screens, sample data, and translation of additional information will
be required. In some cases, where context cannot be derived, implementers or
customers will require additional navigation instruction for the task flow. See the Oracle User Productivity Kit Translation blog entry.
have any other doc or help translatability considerations, tips, or insights to share with UX designers? Cherchez les comments