Translatability Best Practices for Doc and Help
By Ultan O'Broin-Oracle on Aug 19, 2011
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).
- Avoid 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 market.
- 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.
- Avoid alphabetically ordered multiple index entries within a single XML index element. Use the index element structure for different levels of index entries instead.
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.