Sun Software Product Internationalization Taxonomy

Print-friendly Version

4.1.2.3 Help Systems and Documentation

Description

Internationalization of textual objects also applies to help systems and hardcopy and software based documentation. Help systems are often separate applications that use different technologies for handling internationalization of textual objects in graphical or character based interfaces. However, the internationalization principles and issues that relate to software components also apply to help systems. The principles outlined for software components also apply to software based documentation. However, hardcopy and software based documentation have a unique set of linguistic requirements that should be approached differently from software internationalization. These linguistic requirements are discussed in detail in the "Recommendations for Documentation" section.

One key point highlighted in this section is the need to keep software, help, and documentation "synchronized". Synchronized here means using the same source for software, help, and documentation terminology where possible. This simplifies the localization process.

Command Line Interface

Command line interfaces often have basic help information, which you can usually access using a -h option. The internationalization issues here are the same as those outlined in the Command Line Interface subsections of sections 4.1.2.1 and 4.1.2.2.

Man pages, which provide help on UNIX commands, are another command line interface.

Character Interface

Help systems are often character based with character user interfaces (UIs). The issues discussed in the Character Interface subsections of sections 4.1.2.1 and 4.1.2.2 with regard to textual objects also apply here for online help and documentation systems. With any interface, it is always advisable to use the same technology for the online help and UI. As well as making synchronization of textual objects easy, it also means consistent internationalization technology across the software architecture.

Graphical Interface

Some help systems have a graphical user interface (GUI) provided by a special online viewer or browser. The issues relating to textual objects, as discussed in the Graphical Interface subsections of sections 4.1.2.1 and 4.1.2.2, also apply to online help and documentation systems. The comments relating to synchronization in the Character Interface subsection also apply here.

Application Protocols

Not applicable.

Storage and Interchange

Help and documentation data can be stored in different formats depending on the viewer or browser technology. They can also be interchanged between client and server and presented to users in user or system defined formats.

Application Programming Interfaces

Not applicable.

Requirements for Compliance

These requirements apply to the following interfaces:

Command line interface

Character interface

Graphical interface

Storage and interchange

There are no requirements for application protocols and application programming interfaces (APIs).

To ensure proper internationalization for help and documentation systems, you must ensure that the following provide full internationalization support:

Markup language

Authoring tools

Illustration tools

Online viewers

Web browsers

To ensure synchronization of information, use the same technology to both author and render help and documentation systems.

Recommendations for Documentation

Text

1. Develop a standard glossary, and translate consistently across documentation sets.
2. Take into consideration relevant external glossaries, such as industry-standard terminology. If dealing with an after-market product, consistency should be maintained with the main product.
3. Establish standard linguistic style guidelines.
4. Maintain consistency between the documentation and the software's UI.
5. Use clear, concrete language.
6. Avoid slang and idioms.
7. Define acronyms and abbreviations.
8. Avoid cultural references, such as gender-specific roles, humor, ethnic or historical references.
9. When choosing to include cultural references, encapsulate such content into well-defined locations.
10. Customize formats to fit the target country, for example date and time formats and currency formats.
11. Confirm that your localization partner has a leveraging strategy, including any translation memory implementations, for reuse of translations and graphics that have already been localized. This strategy should accommodate both new product releases as well as updates during the localization process.

Layout

1. stablish standard layout guidelines, clearly defining the use of design styles
2. Consider the development of a universal template to reduce layout tasks and time during localization.
3. Use standard fonts that are well supported by most output devices and are easily available. If special fonts are used, it is critical to communicate this to the localization team up-front, prior to localization.
4. Save call-outs, as well as text within tables, as text rather than as graphical elements
5. Leave sufficient white space to accommodate text expansion during translation.
6. Anticipate font type and size modifications for some character sets.
7. Anticipate vertical expansion of the text for some character sets, for example, Traditional Chinese.
8. Avoid formatting characters and paragraphs manually. Instead, define an appropriate style to automate the task and ensure consistency.
9. Automate header and footer text, such as chapter titles and page numbers. This information can change during repagination of the localized documentation.

Graphics

1. Use standard, easily available applications to create graphics in target languages.
2. Avoid using text in icons and graphics, if possible.
3. If text is included, try using callouts or captions with the text component in the DTP application rather than in the graphics file. Otherwise, if the text is within the graphic itself, save the text as editable text, not as pixels.
4. Assume that callouts and text within graphics will increase in length when translated. Leave sufficient white space to accommodate this text expansion.
5. Link graphics rather than embed them whenever possible.
6. For screen captures, note the computer configuration and software settings, such as color depth and screen resolution. Give this information to the localization team.
7. For screen captures requiring complex setup and navigation, identify these and supply regeneration instructions to the localization team.
8. Avoid using culturally-specific icons and graphics.
9. Avoid using representations of people and animals in icons and graphics.

Courtesy of Rubric, Tips for Creating World-ready Documentation, http://www.rubric.com.