Software Localizability Guidelines for Developers
Introduction
As more and more companies are distributing their software products worldwide, better localization practice will help ensure greater success in the competitive global markets. This document provides some general guidelines for software developers and programmers to write better applications for more efficient downstream localization. By addressing internationalization and localization issues early during the software development stage, companies can ensure the resulting applications will be localized into other languages efficiently and with quality. Following these internationalization best practice will help streamline the subsequent localization effort leading to greater return on investment.
Development Tool and Technique
1) When developing a software application, the choice of a development tool or technology must consider if all character sets are supported to ensure the application can be properly localized down the road.
2) For bi-directional languages such as Arabic and Hebrew, the development tool should have built-in support for right to left UI layout as this will help eliminate many technical issues during subsequent localization.
Isolating Localizable Resources
1) One of the most important internationalization practice is to separate all localizable elements from the main source code. The simplest and most straightforward method of isolating localizable resources is to put everything in a source type of resource repository such as Windows resource files (*.rc), .Net assemblies files, or a database when dealing with web content.
2) Make sure that no hard-coded elements/strings (i.e. hard-coded messages, const etc.) are used in the code. Hard-coded elements are difficult to localize because they do not show up until the localized software is compiled and executed. Again, all localizable strings should be separated into one or more resource files. The major program elements that require localization include: menus, messages, dialog boxes, prompts, images, sounds, toolbars, status bars constants etc.
3) Other types of resources related to localization also need to be isolated, such as font, folder names (i.e. Windows My Documents folder path). These kinds of resources should be verified against target language platforms during localization. Otherwise they may have functional impact.
4) Not all resource strings need to be localized. For example, strings or dialogs for debugging, command lines, sample codes and SQL statements don’t need to be localized. They should be separated from localizable resources or be easily identifiable through clear instructions to avoid confusions during localization.
5) Create a list of product/module names and keep them updated. Since most companies do not translate product/module names, efforts should be made to allow the localizer to identify the product or module names easily.
6) Similar to product names, important product terminologies should be included in a master glossary. Good terminology management at the source will go a long way for better translation consistency downstream.
7) Resource files should be developed to compile independently so that the resource compiling environment can be shared with the localization team without exposing the source code.
8) The software development team should create localization test cases for more efficient localization testing. The test cases usually consist of a subset of test cases designed for English (source) version’s functionality testing. Good localization test cases will ensure the localization tester to efficiently go through all important UI dialogs in all target language platforms.
Engineering
1) It is recommended that only the target language OS be used with compiling the localized resource files. For example, if an application is localized into Greek, the localized resource files should be compiled in the Greek version of the Windows system.
2) The development engineer must set up Regional and Language Options (for Microsoft Windows systems, this can be found in the Control Panel) to use the correct target language before editing any localized text files.
3) Use correct and system default font for the target language to display the localized text (i.e. Use SimSun to display Simplified Chinese, use MS Gothic to display Japanese. etc.)
4) Only use English characters, numbers and underscore character in file name so that the files can be opened in any target language platforms. Never use double-byte characters such as Chinese files names for applications files as they will fail to be picked up on a non Chinese system.
5) Keep file format consistent for all resource files. Unicode format is recommended if there are no technical difficulties or problems for the company to support.
6) Original resource files such as RC, HTML and XML should be provided for localization instead of using compiled files such as DLL and CHM. Working with the source files will allow better translation and engineering leverages for future updates.
7) English hotkeys should be embedded in the UI strings (i.e. &File). However, for double byte languages, they should be placed after translated text within parenthesis (i.e.文件(&F)).
String Handling
1) Avoid run-time composite strings like the ones shown in the following example:
StringA = “has been”
StringB = “Validated”
StringC = “Approved”
msg_str = FileName + StringA +StringB + “. Thank you!“
It is important to keep sentences in a single string. When a sentence is broken up into several strings, the strings do not necessarily appear consecutively in the localizer’s string table. It will cause translations issues.
Additionally, the value of a variable often determines whether a different syntax or definite article should be used. For example, in European languages, nouns have gender requirements, and adjectives have four to fourteen different forms that must match the nouns they modify.
2) When variables are necessary, unique names should be used to keep them clear and identifiable in context to ensure the right value or translation is assigned. Here is an example that illustrates this point:
“Please %s the %s”
The variable %s here is not unique. The first variable is a verb and the second one is a file name. However, the verb should come after the file name in some languages, thus the final translation will be wrong in rum-time when the variables are assigned in original string order.
Here is another example:
“%d of %s”
In this case, the translator obviously does not know how to translate the word “of” since it is ambiguous about it means or refers to in this particular context.
3) Do not convert Date variables to strings or use String variables for dates. For example, if a developer converts date to a string and uses the first four characters of string to denote year, it will cause confusions for other languages when translated. Different languages have different number sequence for year, month and day. For example, in French, the first four characters are used to represent day and month, so the developer’s conversion above will lead to a functional error.
4) Do not use concatenatedstrings (i.e. AccountName, Job_Number etc.) or all upper-case strings (i.e. EDIT) as these strings will be regarded as variables that should not be localized.
5) Do not allow the Number of Characters to impact any function as this can cause issue for double byte languages. Each single-byte character takes only one byte, but double-byte character takes two bytes.
6) Do not allow localizable strings to impact any function. The following code should be avoided:
Function GetAnswer (strAnswer)
If strAnswer = ’Yes’ then
…
Design of User Interface (UI)
1) When designing the user interface (UI), please always ensure it’s flexible and neutral. A good practice to minimize the amount of resizing work during localization is to design the source language dialog boxes with as much room to spare as possible. Extend text frames with extra room to accommodate text expansion while still keeping them look aesthetical so they can allow text to grow when it is translated. For European languages, a typical translated sentence is normally about 30-40% longer than the English original, and the increase may be as much as 100-200% for short UI terms. Chinese translation is usually shorter than English on average. However, when the English application uses abbreviation with UI terms, the Chinese translation will definitely need more space to display.
Similar to UI design, enough buffers should be reserved for localization in String type variable definitions.
2) For some controls, such as radio buttons and check boxes please ensure text wrap is enabled to allow multiple lines of text to be displayed. As an example, to allow multiple lines in a Win32 resource file, either manually add the BS_MULTILINE property to the control or select Multiline property in Visual Studio. This practice is also helpful to handle text expansion after localization.
3) Do not use code to dynamically create or resize controls at runtime. Also do not put many overlapping and hidden controls on the UI. These layout treatments can lead to problems in dialog box resizing and localization testing. Ideally the UI layout should always be the same in both design mode and in runtime.
4) The use of images should only be done sparingly as they tend to clog up the UI design and more difficult to extract the strings for translation.
Graphic and Screenshot
1) Any localizable graphic must have corresponding source file. For example, if a designer uses Photoshop to create a diagram and converts it to *.gif. The *.psd file must be saved for localization although the *.gif file is the one used in the software. Also, please ensure the text layers are editable to allow the most efficient string extraction for localization.
2) Localized screenshots used in documents need to be taken from the software after it is localized and tested.
3) Avoid using graphics that might not be applicable or offensive in some locales, including:
· Images that contain text:
o If an image contains English text, the text (and graphic) must be localized for each locale.
· Images that contain numbers:
o Numbers have different connotations in different locales. For example, just as the number 13 has an unlucky connotation in the United States, the number 4 connotes death in both Japan and Hong Kong.
· Images containing hand gestures:
o A gesture that is appropriate or meaningful in one locale can be offensive or meaningless in another locale
§ the “OK” sign
§ A mailbox to represent an email application (because the shape and size of mailboxes vary by locale
· Images that represent everyday objects, holidays, and seasons
· Images depicting humor, puns, and slang
· Image including OS or hardware specific content
o Do not include this content if at all possible. Otherwise the target screenshots will have to be captured in localized version of these OS or hardware, leading to increased localization cost.
· Images of animals
o Just as the image of a dog to represent food would be unsettling to most people in the United States, the image of a cow in the same context can offend people in India.
· Images depicting human body elements and body language
o Depictions of certain facial expressions
o Nontraditional gender dynamics
o Uncovered skin can be offensive to users in some locales.
· Images depicting physical environments
· Images depicting ethnic, racial, political, and religious environments
· Images depicting gender-specific elements
· Images depicting sexual and violent elements
· Images depicting regional conventions
o Reading direction
o Date/time
o Monetary elements
However, there are plenty of symbols and images that work well in all locales and cultures such as the use of a telephone icon to denote the word phone, i.e. (.
4) A valuable resource is the ISO 11581. This is the International Standards Organization (ISO) standardization of the use of internationally accepted icons for the information technology industry - specifically with the use of user interfaces that users can interact with and manipulate.
Culture
1) Avoid culturally specific examples.
2) Avoid showing body parts. There are many differences among cultures for displaying exposed human body. The best practice is not to display skin or use a body part to convey a concept.
3) Beware of gender-specific roles and ethnic stereotypes in other cultures.
4) Avoid using strong color elements in UI design as many colors can have different significance among cultures. Usually, the color blue is widely accepted throughout the world.
