Contents | Prev | Next


Global Products Planning Guide for Java Applications


Introduction

Revision Date: 1/23/98

Internationalizing a product from the beginning enables quick access to worldwide markets, and allows the product to be localized at a lower cost. When retrofitting an existing product to support internationalization, developers should conform to this document's guidelines, even if localized versions of the product already exist.

The goal of this document is to help software developers and managers determine the internationalization requirements for applications written in the Java programming language. It is intended for use by employees and partners of Sun Microsystems, Inc.

The APIs discussed in this document conform to version 1.1.5 of the JDK (Java Development Kit). Additional internationalization APIs are expected in the 1.2 version of the JDK, but the 1.2 APIs are not discussed in this document.

This document is organized according to the "Master Internationalization Taxonomy" framework developed by Sun Microsystems, Inc. Intended as a planning guide, this document is not a tutorial or a programming guide. Software developers who want to learn how to internationalize Java programs will find the following documents helpful:

1 Translatable Product Components

1.1 Translation Negotiations, Defaults and Selection

Locales

On the Java platform, a locale is simply an identifier for a particular combination of language and region. It is not a collection of locale-specific attributes. Instead, each locale-sensitive class maintains its own locale-specific information. With this design, there is no difference in how user and system objects maintain their locale-specific resources. Both use the standard localization mechanism.

Java programs are not assigned a single global locale. All locale-sensitive operations may be explicitly given a locale as an argument. This greatly simplifies multilingual programs. While a global locale is not enforced, a default locale is available for programs that do not wish to manage locales explicitly. A default locale also makes it possible to affect the behavior of the entire presentation with a single choice.

Java locales act as requests for certain behavior from another object. For example, a French Canadian locale passed to a Calendar object asks that the Calendar behave correctly for the customs of Quebec. It is up to the object accepting the locale to do the right thing. If the object has not been localized for a particular locale, it will try to find a "close" match with a locale for which it has been localized. Thus if a Calendar object was not localized for French Canada, but was localized for the French language in general, it would use the French localization instead.

Locale Class

A Locale object represents a specific geographical, political, or cultural region. An operation that requires a locale to perform its task is called locale-sensitive and uses the Locale object to tailor information for the user. For example, displaying a number is a locale-sensitive operation- the number should be formatted according to the customs and conventions of the user's native country, region, or culture.

Supported Locales

On the Java platform, there does not have to be a single set of supported locales, since each class maintains its own localizations. Nevertheless, there is a consistent set of localizations supported by the JDK classes. Other implementations of the Java platform may support different locales than the JDK. Those supported by the JDK are summarized in the following table. Subsequent releases of the JDK may include additional locales.

Table 1 Locales Supported By JDK1.1

Locale

Language

Country

da_DK Danish Denmark
DE_AT German Austria
DE_CH German Switzerland
DE_DE German Germany
el_GR Greek Greece
en_CA English Canada
en_GB English United Kingdom
en_IE English Ireland
en_US English United States
es_ES Spanish Spain
fi_FI Finnish Finland
fr_BE French Belgium
fr_CA French Canada
fr_CH French Switzerland
fr_FR French France
it_CH Italian Switzerland
it_IT Italian Italy
ja_JP Japanese Japan
ko_KR Korean Korea
nl_BE Dutch Belgium
nl_NL Dutch Netherlands
no_NO Norwegian (Nynorsk) Norway
no_NO_B Norwegian (Bokmål) Norway
pt_PT Portuguese Portugal
sv_SE Swedish Sweden
tr_TR Turkish Turkey
zh_CN Chinese (Simplified) China
zh_TW Chinese (Traditional) Taiwan

1.2 Textual Objects

Localized Resources

All locale-sensitive classes must be able to access resources customized for the
locales they support. To aid in the process of localization, it helps to have these
resources grouped together by locale and separated from the locale-neutral parts of the program.

ResourceBundle Class

The class ResourceBundle is an abstract base class representing containers of resources. Programmers create subclasses of ResourceBundle that contain resources for a particular locale. New resources can be added to an instance of ResourceBundle, or new instances of ResourceBundle can be added to a system without affecting the code that uses them. Packaging resources as classes allows developers to take advantage of Java's class loading mechanism to find resources.

Resource bundles contain locale-specific objects. When a program needs a locale-specific resource, a String object for example, the program can load it from the resource bundle that is appropriate for the current user's locale. In this way, the programmer can write code that is largely independent of the user's locale isolating most, if not all, of the locale-specific information in resource bundles.

This allows Java programmers to write code that can:

ListResourceBundle Class

ListResourceBundle is an abstract subclass of ResourceBundle that manages resources for a locale in a convenient and easy to use list.

PropertyResourceBundle Class

PropertyResourceBundle is a concrete subclass of ResourceBundle that manages resources for a locale using a set of static strings from a property file.

1.2.1 Identifiers, Labels, Keywords

1.2.2 Messages

ChoiceFormat Class

The class ChoiceFormat is a concrete subclass of the NumberFormat class. The ChoiceFormat class allows the programmer to attach a format to a range of numbers. It is generally used in a MessageFormat object for handling plurals. See the "MessageFormat Class" section that follows for more information.

MessageFormat Class

Programs often need to build messages from sequences of strings, numbers and other data. For example, the text of a message displaying the number of files on a disk drive will vary:

If a message built from sequences of strings and numbers is hard-coded, it cannot be translated into other languages. For example, note the different positions of the parameters "3" and "G" in the following translations:

The class MessageFormat provides a means to produce concatenated messages in language-neutral way. The MessageFormat object takes a set of objects, formats them, and then inserts the formatted strings into the pattern at the appropriate places.

1.2.3 Other (Help, doc, ....)

1.3 Non-Textual Objects

Resource bundles objects that are locale-specific. Often, these objects are textual, but they may also be non-textual objects. For more information, see "ResourceBundle Class" for more information.

1.3.1 Icons, Images, Colors

1.3.2 Sounds

1.3.3 Other

2 Cultural Formatting and Processing

2.1 Culture Negotiations, Defaults and Selection

2.2 Abstract Objects

2.2.1 Time, Date, and Calendar

Calendar and Time Zone Support

JDK 1.0 introduced the java.util.Date class for the representation of dates and times. The java.util.Date class allowed for the interpretation of dates as year, month, day, hour, minute, and second values, and it formatted and parsed date strings. Unfortunately, the API for these functions was not amenable to internationalization. Only the "representation" part of this class is retained in JDK 1.1.

As of JDK 1.1, the Date class should only be used as a wrapper for a date or time. That is, Date objects represent a specific instant in time with millisecond precision. Instead, programmers should use the Calendar class to convert between date and time fields, and the DateFormat class to format and parse date strings. The corresponding methods in the JDK 1.0 version of the Date class have been deprecated.

Calendar Class

The class Calendar is an abstract base class which can convert between a point in time (represented as milliseconds from 00:00:00 GMT, Jan 1, 1970) and a set of integers representing the year, month, week and so on. GregorianCalendar is a concrete subclass of Calendar that does this according to the rules of the Gregorian calendar.

Calendar and its subclasses are useful for doing various manipulations with time values. Arithmetic can be performed on a Calendar object's fields and the resulting date determined. A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style

TimeZone Class

The abstract class TimeZone encapsulates a time zone offset from UTC (Universal Coordinated Time) and a possible daylight-savings time offset. The class SimpleTimeZone is a concrete subclass that encapsulates some simple rules about daylight-savings time. These rules do not take into account historical changes in the laws affecting daylight-savings time. The Calendar class and its subclasses use the TimeZone and SimpleTimeZone classes to convert between local time and UTC, which is the internal representation used by Date objects. Most programs will not have to deal with TimeZone objects directly.

DateFormat Class

Dates and times are stored internally in a locale-independent way, but should be formatted so that they can be displayed in a locale-sensitive manner. For example, the same date might be formatted as:

The class DateFormat is an abstract base class for formatting and parsing date and time values in a locale-independent manner. It has a number of static factory methods for getting standard time formats for a given locale.

The DateFormat object uses Calendar and TimeZone objects in order to interpret time values. By default, a DateFormat object for a given locale will use the appropriate Calendar object for that locale and the system's default TimeZone object. The programmer can override these choices if desired.

SimpleDateFormat Class

The class SimpleDateFormat is a concrete class for formatting and parsing dates and times in a locale-sensitive manner. It allows for formatting (milliseconds to text), parsing (text to milliseconds), and normalization.

DateFormatSymbols Class

The class DateFormatSymbols is used to encapsulate localizable date-time formatting data, such as the names of the months, the names of the days of the week, time of day, and the time zone data. The DateFormat and SimpleDateFormat classes both use the DateFormatSymbols class to encapsulate this information.

Usually, programmers will not use the DateFormatSymbols directly. Rather, they will implement formatting with the DateFormat class's factory methods.

2.2.2 Number, Monetary, Metrics

NumberFormat Class

The class NumberFormat is an abstract base class for formatting and parsing numeric data. It contains a number of static factory methods for getting different kinds of locale-specific number formats.

The NumberFormat class helps programmers to format and parse numbers for any locale. Code using this class can be completely independent of the locale conventions for decimal points, thousands-separators, the particular decimal digits used, or whether the number format is even decimal. The application can also display a number as a normal decimal number, currency, or percentage:

DecimalFormat Class

Numbers are stored internally in a locale-independent way, but should be formatted so that they can be displayed in a locale-sensitive manner. For example, when using "#,###.00" as a pattern, the same number might be formatted as:

The class DecimalFormat, which is a concrete subclass of the NumberFormat class, can format decimal numbers. Programmers generally will not instantiate this class directly but will use the factory methods provided.

The DecimalFormat class has the ability to take a pattern string to specify how a number should be formatted. The pattern specifies attributes such as the precision of the number, whether leading zeros should be printed, and what currency symbols are used. The pattern string can be altered if a program needs to create a custom format.

DecimalFormatSymbols Class

The class DecimalFormatSymbols represents the set of symbols (such as the decimal separator, the grouping separator, and so on) needed by DecimalFormat to format numbers. DecimalFormat creates for itself an instance of DecimalFormatSymbols from its locale data. A programmer needing to change any of these symbols can get the DecimalFormatSymbols object from the DecimalFormat object and then modify it.

2.3 Structured Text

2.3.1 Ordered Lists (Collation)

Locale-Sensitive String Operations

Programs frequently need to manipulate strings. Common operations on strings include searching and sorting. Some tasks, such as collating strings or finding various boundaries in text, are surprisingly difficult to get right and are even more difficult when multiple languages must be considered. The JDK provides classes for handling many of these common string manipulations in a locale-sensitive manner.

Collator Class

The Collator class performs locale-sensitive string comparison. Programmers use this class to build searching and alphabetical sorting routines for natural language text. Collator is an abstract base class. Its subclasses implement specific collation strategies. One subclass, RuleBasedCollator, is currently provided with the JDK and is applicable to a wide set of languages. Other subclasses may be created to handle more specialized needs.

RuleBasedCollator Class

The RuleBasedCollator class, which is a concrete subclass of the Collator class, provides a simple, data-driven, table collator. Using RuleBasedCollator, a programmer can create a customized table-based collator. For example, a programmer can build a collator that will ignore (or notice) uppercase letters, accents, and Unicode combining characters.

CollationElementIterator Class

The CollationElementIterator class is used as an iterator to walk through each character of an international string. Programmers use the iterator to return the ordering priority of the positioned character. The ordering priority of a character, or key, defines how a character is collated in the given Collator object. The CollationElementIterator class is used by the compare() method of the RuleBasedCollator class.

CollationKey Class

A CollationKey object represents a string under the rules of a specific Collator object. Comparing two CollationKey objects returns the relative order of the strings they represent. Using CollationKey objects to compare strings is generally faster than using the Collator.compare() method. Thus, when the strings must be compared multiple times, for example when sorting a list of strings, it is more efficient to use CollationKey objects.

2.3.2 Personal Names, Honorifics, Titles

2.3.3 Abstract Labels, Addresses

2.3.4 Other Formatting, Layout, Orthography

2.4 Language Processing

2.4.1 Structure (Morphology, Syntax)

BreakIterator Class

The BreakIterator class indirectly implements methods for finding the position of the following types of boundaries in a string of text:

The conventions on where to break lines, sentences, words, and characters vary from one language to another. Since the BreakIterator class is locale-sensitive, it can be used by programs that perform text operations. For example, consider a a word processing program that can highlight a character, cut a word, move the cursor to the next sentence, or word-wrap at a line ending. This word processing program would use break iterators to determine the logical boundaries in text, enabling it to perform text operations in a locale-sensitive manner.

StringCharacterIterator Class

The StringCharacterIterator class provides the ability to iterate over a string of Unicode characters in a bidirectional manner. This class uses a cursor to move within a range of text, and can return individual characters or their index values. The StringCharacterIterator class implements the character iterator functionality of the CharacterIterator interface.

CharacterIterator Interface

The CharacterIterator interface defines a protocol for bidirectional iteration over Unicode characters. Classes should implement this interface if they want to move about within a range of text and return individual Unicode characters or their index values. CharacterIterator is for searching is useful when performing character searches.

2.4.2 Lexical (Dictionaries, Spelling, Word Exp.)

2.4.3 Other (Phonology, SOUNDEX)

3 Writing System (Text) Foundation

3.1 Writing System Negotiation, Defaults and Selection

3.2 Plain Text Foundation

3.2.1 Characters (Semantics, Codespaces)

Character Classification

The Java platform stores character data in Unicode- an international character set standard. The Unicode Standard uses a 16-bit encoding to support all of the major scripts of the world, as well as common technical symbols. Most Java code is written in ASCII, a 7-bit standard, or ISO-Latin-1, an 8-bit standard, but is translated into Unicode before processing. Therefore, the Java character set is always represented in Unicode.

JDK 1.0 introduced the Character class as an object wrapper to the char primitive type. The Character class also contained some static methods such as isLowerCase() and isDigit() for determining the properties of a character. This set of methods has been extended in JDK 1.1 to allow access to all the Unicode 2.0 defined properties for a character.

3.2.2 Strings (Encoding Methods, Transcoding)

ParsePosition Class

The class ParsePosition is used by the Format class and its subclasses to keep track of the current position during parsing. The parseObject() method in the Format class requires a ParsePosition object as an argument.

FieldPosition Class

The FieldPosition class is used by the Format class and its subclasses to identify fields in formatted output. One version of the format() method in the Format class requires a FieldPosition object as an argument.

3.3 I/O and Interchange

Stream I/O

JDK 1.1 provides two major enhancements to the java.io package to improve the handling of character date: the new Reader and Writer classes, and an enhancement to the PrintStream class.

Reader and Writer Classes

The Reader and Writer class hierarchies provide the ability to perform I/O operations on character streams. These hierarchies parallel the InputStream and OutputStream class hierarchies, but operate on streams of characters rather than streams of bytes. Character streams make it easy to write programs that are not dependent upon a specific character encoding, and are therefore easier to internationalize. The Reader and Writer classes also have the ability to convert between Unicode and other character encodings. Please refer to the Character Streams document for more information about the Reader and Writer class hierarchies.

PrintStream Class

The PrintStream class has been enhanced to produce output using the system's default character encoding and line terminator. This change allows methods such as System.out.println() to act more reasonably with non-ASCII data.

3.3.1 Transfer Encoding (8-bit clean)

Character Set Conversion

The Java platform uses Unicode as its native character encoding; however, many Java programs still need to handle text data in other encodings. Java therefore provides a set of classes that convert many standard character encodings to and from Unicode. Java programs that need to deal with non-Unicode text data will typically convert that data into Unicode, process the data as Unicode, then convert the result back to the external character encoding. InputStreamReader and OutputStreamWriter classes provide methods that can convert between other character encodings and Unicode.

Supported Encodings

The InputStreamReader and OutputStreamWriter classes can convert between Unicode and the following set of character encodings:
Table 2 JDK1.1 Character Encodings

Character encoding

Explanation

8859_1 ISO Latin-1
8859_2 ISO Latin-2
8859_3 ISO Latin-3
8859_4 ISO Latin-4
8859_5 ISO Latin/Cyrillic
8859_6 ISO Latin/Arabic
8859_7 ISO Latin/Greek
8859_8 ISO Latin/Hebrew
8859_9 ISO Latin-5
Big5 Big 5 Traditional Chinese
CNS11643 CNS 11643 Traditional Chinese
Cp1250 Windows Eastern Europe / Latin-2
Cp1251 Windows Cyrillic
Cp1252 Windows Western Europe / Latin-1
Cp1253 Windows Greek
Cp1254 Windows Turkish
Cp1255 Windows Hebrew
Cp1256 Windows Arabic
Cp1257 Windows Baltic
Cp1258 Windows Vietnamese
Cp437 PC Original
Cp737 PC Greek
Cp775 PC Baltic
Cp850 PC Latin-1
Cp852 PC Latin-2
Cp855 PC Cyrillic
Cp857 PC Turkish
Cp860 PC Portuguese
Cp861 PC Icelandic
Cp862 PC Hebrew
Cp863 PC Canadian French
Cp864 PC Arabic
Cp865 PC Nordic
Cp866 PC Russian
Cp869 PC Modern Greek
Cp874 Windows Thai
EUCJIS Japanese EUC
GB2312 GB2312-80 Simplified Chinese
JIS JIS
KSC5601 KSC5601 Korean
MacArabic Macintosh Arabic
MacCentralEurope Macintosh Latin-2
MacCroatian Macintosh Croatian
MacCyrillic Macintosh Cyrillic
MacDingbat Macintosh Dingbat
MacGreek Macintosh Greek
MacHebrew Macintosh Hebrew
MacIceland Macintosh Iceland
MacRoman Macintosh Roman
MacRomania Macintosh Romania
MacSymbol Macintosh Symbol
MacThai Macintosh Thai
MacTurkish Macintosh Turkish
MacUkraine Macintosh Ukraine
SJIS PC and Windows Japanese
UTF8 Standard UTF-8

OS Support For Character Conversions

Some platforms may provide their own primitives for conversion to and from Unicode. These conversions likely will differ from those provide by the Java classes in the following respects:

For these reasons, the JDK provides its own standard mappings, but allows platform specific extensions to fit in the general model.

The native2ascii Utility

The native2ascii program converts a file with native-encoded characters (characters which are non-Latin 1 and non-Unicode) to one with Unicode-encoded characters.

3.3.2 Device Input (Keyboard, IM)

3.3.3 Device Output (Font Mgmt, Rendering, OM)

Classes Related to Fonts

The AWT supports multiple type fonts, which are encapsulated by the Font class. The Font.getFont() method returns the font associated with the specified system property.

To determine which fonts are available, the programmer should invoke the getfontList() method, which belongs to the Toolkit class.

The abstract class FontMetrics gives information about the rendering of a font.

Font Properties File

The programmer must work with the font.properties file to add fonts to the Java Runtime Environment. The font.properties file is platform- specific. It indicates the fonts that a particular platform uses for its Java virtual fonts. Fonts are grouped by types or classes. There are several font.properties files that come bundled with the JDK. You can find these files in the lib subdirectory where the JDK is installed.

See the following web pages for more information about font.properties files:



Contents | Prev | Next
dale.green@Eng.sun.com
Copyright © 1996, 1997 Sun Microsystems, Inc. All rights reserved.