Every application should be designed with international users in mind. Though your target audience might be entirely in one country initially, the situation might change in the future. Some applications grow over time, and some application designs are recycled into new applications that might have different target audiences. This section describes some code techniques for dealing with international applications.
This article is not meant to be an all-encompassing detail of how to internationalize an application. There are many resources available on the Internet to assist with further details of the items discussed below.
Dates and times
When displaying dates, be aware that not everyone views a date value the same. For example, 10/11/12 could mean the 10th of November or the 11th of October. It is best to show dates with a month name (either abbreviated of spelled out). It is also best to always use a four-digit year, to decrease confusion.
To format a date in the current user's locale, there are built-in Java classes to do this. As an example, this code shows the current date (“now”) and current time in the user's defined LONG date format:
If designing a Notes client application, take advantage of the client's capability to format dates according to the user's local preferences. This mainly means that you should avoid converting date/times to string values that you then store in the database. Dates and times should be stored using the built-in date-time item type, and only converted by the user's client.
As an example of what not to do, consider the following field formula for a computed field:
"Updated by " + @V3UserName + " on " + @Text(@Today)
If a document is edited by a user in France, let's say, then the field is assigned a value such as "Updated by Michelle Dubois on 7/4/2012", meaning April 7th. But users in some other places -- the USA, for instance -- are used to seeing the month first, so they are likely to misinterpret this as July 4th. What's worse, because the value in each document reflects the settings of the user who last edited it, the documents are not even consistent in how they format dates; in some, "7/4" means April 7th, in others it means July 4th.
To avoid such difficulties, your application should store this information in two fields -- a Text field for the name of the editing user, and a date/time field for the date. Since the client calculates how to display the date when the user opens the document, the user's preferred settings will always be used. Even if you override the default formatting to specify that dates will always be displayed in U.S. format, at least then your formatting will be consistent.
A similar situation occurs in view column formulas, when @Text is used to convert date/times. Because the view index is calculated by the server, the conversion takes place according to the server's settings rather than those of the end user. It is generally better, if your column is to display a date or time value, to have a view column formula that returns a date/time value, not text. You can use the column settings to control formatting if you wish, but it's usually better to let the users see dates in the format that they have established as their personal preference.
NOTE: While you would want to avoid using @Text to convert a date in a computed field or computed when composed, it's fine to do this in a computed for display
field, since the value in that case is not stored, but only used locally.
NOTE: in the above example, it's also a bad idea to make the text "Updated by" and "on" part of the field value, since that will cause problems if you make the application multilingual later, and because it's a waste of space to store these characters in every document.
When displaying time values, you should make it clear what time zone they are in. Either display the zone, or if you convert all times to the local time zone, indicate this somehow (e.g. by the text "(local time)" after the value. A time of 8:00 AM means quite different things if it is 8:00 AM Greenwich Mean Time or 8:00 AM Hawaiian Standard Time. The Edit Box controls in XPages and the Date/Time fields in forms and views can easily show the time zone along with the time value. There is a TimeZone field type which can be used to select a time zone in traditional Notes development. A TimeZone field converts to a combo box with all the available time zones on the web.
In XPages development, there is an application property which says if the time zone should use the server default (choice comes from a properties file), the user's time zone, or the server's time zone. There is also a TimeZone object in Java that can be used. For more information about using time zones in your XPages development, refer to the wiki article Time Zones in XPages
Another zone issue can result from using the LotusScript date/time variant datatype to assign date-only values to document fields. For details, and general recommendations and troubleshooting for working with date/time values, consult the Designer wiki document, Working with Date/Time Values in Lotus Notes
If you need a particular component of a date -- if you want just the year, for instance -- do not convert the date to text, then use string functions (Mid$, @Explode, etcetera) to find the year, month or day. Your code will break when used by someone with different preferences than yours -- which can occur even if the user is in the same city.
- Determine if the user has a decimal or comma as the separator between the whole amount and the fractional amount
- Use the “other” character as the thousands separator
- Format the number appropriately
var decimalSep = Number("1.5").toLocaleString().substr(1,1);
Concerns of the decimal and thousands delimiter being different with different users also apply when developing Notes client applications. As explained above regarding date/time values, when working with numbers, it's better to store the number in an item of type Number, not as text. Avoid using @Text in computed field formulas and view column formulas.
If displaying a value with a currency symbol, bear in mind that the local currency symbol is an OS preference also. If your value is in US dollars (let's say), make sure you specify $ as your currency symbol in the formatting settings of Notes fields and view columns. Otherwise, users in other countries will see their local currency symbol beside the number.
There is not an value type in Lotus Notes that includes an amount and
a currency selection; you would have to store this information in two separate fields.
When possible, application output should be available in a variety of languages. This broadens the audience for your application and decreases confusion for uses who do not speak your language fluently. The wiki article "XPages: How to use the localization options"
describes how to use multiple languages for your XPage applications.
For Notes client applications, Domino Global Workbench
(DGW) provides a way to convert a single-language application into multiple languages. It extracts strings and creates properties files which you can hand over to translators; then you use DGW again to import the files to create different national-language versions of each design element in your application. So for instance, your one NSF would contain a form in English, and the same form in French, and so on. Notes client users will be presented the version of the form, view or whatever that corresponds to their language preference.
NOTE: Views have performance impact, as described elsewhere in this guide. Do not use the "Automatic" indexing option for views in multilingual applications, since that will cause all language versions of the view to be indexed on all servers, even if nobody on the server uses that language. "Auto on first use" is a better choice. You might also want to discard indexes after a shorter number of days than you otherwise might.
The I18n class in XPages
You can use the I18n class to perform many types of conversions and result in correct displays of information based on the locale of the reader. The following example displays a date and time in your desired format:
There are many date patterns available.
The I18n class can also be used to convert a time from one time zone to another time zone. For example, you can display the time in both Greenwich Mean Time and the user's current time zone.
Parent topic: 4.0 Coding techniques