An Oracle blog about translation

Translatability Best Practices for Doc and Help

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
  • 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
Use the indexing and keyword elements as intended

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

    Avoiding use programlisting or equivalent code elements for tables.

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.
 Do you have any other doc or help translatability considerations, tips, or insights to share with UX designers? Cherchez les comments.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.