Internationalization

The software market is becoming increasingly globalized, now spanning multiple languages and cultures. This shift bears directly upon how applications are designed ”it requires that software can be easily reengineered for different languages so that products can achieve their full market potential. To this end, this section addresses the issue of Internationalization (I18N) ”a proactive development methodology that aims to minimize the effort required to redeploy software in different languages. The process of reworking software for different languages is known as Localization (L10N). Internationalization requires careful consideration of several design issues from the outset. This section introduces these general issues and details the facilities that Series 60 provides to help developers address them.

General Guidelines for Developers

The goal of Internationalization is to make it easy for your application to transcend not languages exactly, but locales. A locale is composed of a base language, but it encompasses more than just this. To clarify this concept, consider that the United States (US) and the United Kingdom (UK) use different locales ( en_US and en_UK , respectively). Though they share English as their base language, there are still differences in the way that they represent certain information. For example, the US uses the "$" (dollar) currency symbol and the UK uses "A3" ( pound ). Also, date formatting is different for each (typically DD/MM/YYYY for the UK and MM/DD/YYYY for the US). Locales, therefore, encompass not just language, but all regional data-representation conventions.

You must take several things into consideration when creating applications that can be localized efficiently . The three basic things to consider are:

• Be sensitive to all data whose representation is locale specific. This includes various conventions such as date and time, monetary and decimal formatting and so on.

• Understand the concept of a locale, and what this means in Series 60.

• Understand how applications use resource files ”this is covered in more detail in Chapter 5.

• Understand how to prepare resources for easy translation.

All data that is not globally recognizable (in other words, data whose formatting is locale specific) needs to be considered from the start, and treated differently. Examples of data that will be different according to the locale are dates, times, currency and, of course, all user -visible text. Perhaps less apparent is the fact that sounds, images and filenames may also need to be locale-specific .

The proper way to treat locale-specific data is to use the special classes offered by the Locale Settings API. These classes represent data according to the locale that is loaded on the given device. So, these special classes work with the application framework in order to deliver output that is correct for a given locale.

Examples of these classes are:

• TLocale

• TLanguage

• tday, TDateName and tdayNameAbb

• TMonth, TMonthName and TMonthNameAbb

• TDateSuffix

• TAmPmName

• TCurrencySymbol

Their names indicate their purpose, but further information is available on each class in the SDK documentation.

Hardware devices come from the factory with a particular default locale loaded on them. Therefore, US phones and UK phones running software that uses these classes will end up displaying data slightly differently. Here is an example of how developers should format a date so that it will be rendered in accordance with the device locale:

 void CMyDateField::DateFieldTextL(const TTime aTTime, TDes& newDateText)    {    atTime.FormatL(newDateText, TShortDateFormatSpec());    } 

This function is deceptively simple looking. However, it accomplishes a lot for you behind the scenes. The FormatL() function formats the date, using the systemwide locale settings encapsulated by the class TShortDateFormatSpec . For the en_UK locale, this function would produce a date formatted such as " 25/12/2003 ". As an alternative, you could use TLongDateFormatSpec , which would produce the equivalent " 25th December 2003 ".

Developers must keep in mind that all user-visible text and locale-specific data will change, once localized ”the obvious consequences are that text may take up more (or less) space in some languages than others, and consequently more (or less) memory. This means that users should avoid fixed- size text buffers. Wherever possible, dynamic buffers should be used instead.

If you have to make decisions about the maximum length of resource strings, then in general you should allow at least 30% extra space for translated text. If the string is just a single word, allow for an expansion of at least 100%.

The following excerpt demonstrates two ways to create dynamically allocated text buffers, with both methods passing ownership out and leaving the created buffer on the Cleanup Stack:

 HBufC* message = StringLoader::LoadLC(R_DIALOG_TEXT); HBufC* msg1 = iEikonEnv->AllocReadResourceLC(R_MY_TEXT_01); 

These functions both dynamically load in a string from a resource, without having to specify the size of the HBufC in the code. CCoeEnv::AllocReadResourceLC() is the traditional Symbian OS method for achieving this and will be commonly seen in old code. The StringLoader class is new to Series 60 but provides a more flexible API for formatting strings as they are read in. Further information on both methods can be found in the SDK documentation.

In your code, do not concatenate strings to produce longer sentences. For example, in Finnish, the phrase "new message received" can be can translated to "uusi viesti saapunut", but if you wanted to say "3 new messages received", the Finnish would be "3 uutta viestiE4 saapunut". "New" has a different translation depending on the sentence , so just joining words together does not work!

Succeeding in producing an easily localizable application means that developers must also think carefully about the text they display on the screen. Menu items should be kept short and to the point. The longer they are, the greater the chance for significant length variation in other languages, which can pose significant UI problems. Thinking along these lines will greatly increase the localizability of applications.

OS Support for Localization

The most important aspect of internationalization is to understand that an application's resource files are not loaded until runtime. Furthermore, the framework provides a special nomenclature for resource files ”it allows multiple resource files, each localized for a particular language, for any given application. The name of each compiled resource file, such as *.r01, *.r02, *.r03 and so on, indicates to the framework the locale that each file represents. For example, English is 01 , French is 02 and so on. When the application is loaded, the framework can then, depending on the device's locale, load the appropriate one.

Installing multiple localized resource files onto a device whose locale setting is unlikely to change is an inefficient use of memory. To remedy this, Series 60's application installation process can optionally prompt users for their preferred language, and then install only that resource file. Refer to the Multi-Locale Installation section in Chapter 2 to understand how your application can benefit from this feature.

The typical way to build applications so that they have locale-independent .rss files is to refrain from hard-coding any text strings in the .rss file itself. Instead, the .rss file should include a .loc file. This .loc file then acts as a large switch:

 #ifdef LANGUAGE_01 #include "Language.l01" #endif #ifdef LANGUAGE_02 #include "Language.l02" #endif #ifdef LANGUAGE_03 #include "Language.l03" #endif #ifdef LANGUAGE_06 #include "Language.l06" #endif 

Each individual .loc ( *.l01 , *.l02 and so on) file then contains all the text strings for each locale. Within the project's .mmp file, you can specify all of the locales for which you want to compile the application. Consider the following .mmp file, which specifies that it should be compiled for six different languages:

 TARGET  HelloWorldLoc.app TARGETTYPE  app UID  0x100039CE 0x101FDA4E TARGETPATH \system\apps\HelloWorldLoc ... LANG 01 02 03 

The LANG instruction tells the resource compiler to compile three different compiled .rsc files. As a result, three compiled files will be produced: ( language.r01 , language.r02 and so on). Changing the locale of a phone will result in a change in which resource file gets loaded. Note that caption resource files can also be localized and the AIF file written to allow the application icon to be locale dependent.

Series 60 supports non-Latin-based character sets, such as Chinese. Additionally, bidirectional text support has been added to version 2.x.