Introduction

The global connectivity provided by the Internet will increase the demand for internationalized software products and place additional requirements on internationalized applications. For example, applications that are delivered and run over the Internet may need to adapt to the user's language at run time. Other applications will need to be multilingual and support a combination of different languages. Java was designed to support internationalization—its primitive character type is based on Unicode, an international standard for encoding written language elements. The Microsoft SDK for Java enhances the internationalization features of Java with support for local character set encoding, Microsoft® Win32® resources, locales, vertical writing, and Java-based input method editors (IMEs).

Enhanced internationalization support is provided by the following Microsoft packages:

• Package com.ms.ui.resource provides support for using Win32 resources in Java applications.
• Package com.ms.lang includes the SystemX class that provides system-level internationalization services, such as managing IMEs and converting strings between local code pages and Unicode.
• Package com.ms.util.InputMethod provides support for creating Java-based IMEs.
• Package com.ms.fx provides FxFormattedText, the standard text layout class, for vertical writing in Far Eastern languages.

In addition to the enhanced support provided by the packages in the preceding list, the Microsoft Win32 VM for Java (Microsoft VM) includes fully functional versions of the java.lang.Runtime methods getLocalizedInputStream and getLocalizedOutputStream.

Creating Multilingual Java Applications using Win32 Resources

Resources are used to isolate text and user interface elements, such as menus and dialog boxes, from the executable part of an application. Although the advantages of using resources apply to all applications, resources are particularly useful in applications requiring internationalization. Resource files can be localized and tested without having to rebuild an entire application. Using resources also decreases size and shortens load time for .class files, as they are not implemented with large amounts of static data.

The Microsoft SDK for Java supports a compact resource format. The com.ms.ui.resource.ResourceDecoder class is an extensible class designed to load resources from a binary file. The com.ms.ui.resource.Win32ResourceDecoder class reads resources in the Win32 resource format. This class also provides methods for accessing the individual resource elements within a resource file. This enables you to use existing resource files with Java applications and to use familiar tools and processes to create and localize new resources.

One problem with current development tools is that they are not necessarily capable of modifying resources in multiple languages within the same file. For example, a common problem is merging Far Eastern language resources with Western ones due to operating system limitations. The Microsoft SDK for Java includes the resmerge utility to address this problem. It enables you to develop resources separately, and then combine resources for different languages into one .res file. When you load Win32 resources from these combined resource files, you can specify the combined resource file as a source, and the language of the resource (the LCID) that you want to load.

There are four steps used in creating a Java application that uses localized resources.

1. Develop the application.
   • Design your application so that you don't set fonts for resources you are loading. The Microsoft VM for Java automatically assigns default system fonts for loaded resources.
   • Make sure you take multilingual requirements (vertical writing, and so on) into account and set the size for GUI elements (for example, dialog boxes) accordingly.
2. Create the resource files, and localize them with existing resource localization tools.
3. Merge the localized resource files using the resmerge utility, if necessary.
4. Use the Win32ResourceDecoder class to access and load localized resources from your Java application.

For example, if you wanted to be able to load both a Chinese and an English string resource, you would first develop these two resources, and then combine them using resmerge.

C:\..\>resmerge -a resources.res MyProjResUS.res MyProjResJP.res

Using Multilingual Java Applications with Win32 Resources

Using Win32 resources in an application is easy. You link to the file and extract the resource using the Win32ResourceDecoder. For example, to populate a panel with localizable controls, you create a resource file that contains dialog resources with the controls laid out as you want them. Execute the following code at run time:

public void populate(UIPanel p, int id)
{ 
    Win32ResourceDecoder res=new Win32ResourceDecoder("resources.res");
    try
    {
        res.populateDialog(p, id);
    }
    catch (Exception e)
    {
        System.out.println("Problem "+e);
    }
}

Note that a locale identifier (LCID) is not used because you will typically load the resources in the language the user needs. However, you can specify a language for any resource by adding the LCID to the method call. For example, an English/Greek dictionary would specify that the list of translated words be loaded in those languages, even if the application is currently being used by someone in Germany, and if all the rest of the user interface is in German.

Note Using Win32 resources allows you to localize your Java applications, without giving your Java source code to localization translators. This way, there will be no confusion between literal text strings and text that should be localized.

Enhanced Locale Support

The Microsoft VM includes the following enhancements to the Locale class to support internationalization.

• Locale support for all locales supported by Win32. This enhancement adds more than forty locales to the locales supported by JDK 1.1, including locales that use vertical writing (for example, Locale.JAPANESE_VERTICAL).
• A new method, getLCID, to get the locale identifier.
• A new method, getCodePage, to get the code page associated with a locale.

Vertical Writing Support

Traditional Chinese and Japanese texts are written vertically—characters appear in a vertical line from the top to the bottom of the page, with lines progressing from the right to the left side of the page. The Microsoft VM supports vertical writing with the FxFormattedText class. There are two ways to specify that the text for an FxFormattedText buffer be written vertically:

• Use the setLocale method to set the locale to a locale that uses vertical writing. Locales that use vertical writing are Locale.TRADITIONAL_CHINESE_VERTICAL, Locale.SIMPLIFIED_CHINESE_VERTICAL, Locale.KOREAN_VERTICAL, and Locale.JAPANESE_VERTICAL.
• Use the setTextDirection method to set the text direction to top-to-bottom, and right-to-left (FxFormattedText.tdTB_RL).

The following sample code implements a panel that contains vertical writing.

class VerticalWritingSample extends UIPanel
{
    FxFormattedText fxft;

    public VerticalWritingSample ()
    {
        fxft = new FxFormattedText ("Vertical Text!");
        fxft.setLocale (Locale.JAPANESE_VERTICAL);
    }
    
    public void paint (FxGraphics g)
    {
        fxft.paint (g);
    }
}

Note When written vertically, characters are rotated 90 degrees (clockwise). This rotation is in accordance with the conventions of vertical writing for traditional Chinese and Japanese texts.

Input Method Editors

An input method editor (IME) is a program that allows computer users to enter complex characters and symbols, such as Japanese Kanji characters, by using a standard keyboard. Internationalized versions of Microsoft® Windows® provide native system IMEs for locales with languages using non-Latin alphabets (for example, Japanese, Korean, Traditional Chinese, and Simplified Chinese). The Microsoft VM provides IME support for Java applications with an Input Method Manager (IMM) that hosts Java-based IMEs, as well as native system IMEs.

Native System IMEs

The Microsoft VM supports existing native system IMEs interchangeably with Java-based IMEs. However, there are some limitations associated with using system IMEs. You can use a Java-based IME on any system, regardless of what language the system is localized for as long as the Microsoft VM is installed. With native system IMEs, however, you are limited to IMEs supported by the host system.

Java-Based IMEs

The Microsoft VM for Java fully supports IMEs written in the Java language. Java-based IMEs provide more flexibility and control for applications than native system IMEs. The following is a summary of the features of Java-based IMEs.

Feature	Description
Unicode-based	Java IMEs can be used with any version of Microsoft Windows.
Cross-platform	Java IMEs will run on any system that has the Microsoft VM installed.
Multilingual	Java IMEs for different languages can be activated concurrently by a single Java application (provided the proper fonts are installed on the user's system).
Web-downloadable	Java IMEs can be packaged and downloaded with applets or downloaded at the discretion of the user.
Managed by the application	Applications can control Java IME interface elements such as composition, status, and candidate windows.
Secure	Java IMEs follow normal Java security rules and run in the "sandbox" with Java applications.

Writing a Java-Based Input Method Editor

The com.ms.util.InputMethod package contains the following classes for creating Java-based IMEs.

• The IMECompositionMessage class represents messages sent to the composition window of an IME.
• The IMENotifyMessage class represents messages sent to an IME to notify it to perform an action on the status or candidate windows.
• The InputMethodCallback class is an interface class that enables an IME to return composed characters and messages to the IMM.
• The InputMethodListener class is an interface class that IMEs must implement to be used with the IMM.

Note The Microsoft SDK for Java includes a sample application, SampleIME, that illustrates how to write a simple, Java-based IME.

Handling Keystrokes

Keystrokes are passed from the Microsoft VM to the IMM, which routes them to the IME. To receive keystrokes, the IME must override the InputMethodListener.handledKey method. The imeCallback parameter in InputMethodListener.handledKey specifies an InputMethodCallback object that allows the IME to send messages back to the Microsoft VM. When composition is complete, the IME should use the InputMethodCallback.handleIMEChar method to return the composed Unicode character to the Microsoft VM.

Note Keystrokes are represented by virtual key codes defined by the KeyEvent class in the java.awt.event package. Keyboard state codes (ALT, CTRL, SHIFT, and so on) are defined in the InputManagerListener class.

Using IMEs with Java Applications

You don't have to do anything special with your Java application to use native system IMEs. If a native system IME is present on a system running the Microsoft VM, it will correctly process and route IME-composed strings to the application.

If you want to use a Java-based IME with your application, you'll need to use the IMM to activate the IME that you want to use. The following list shows the classes you use to work with the IMM.

• The SystemX class (in the com.ms.lang package) enables you to get and set the default IMM provided by the Microsoft VM.
• The InputManagerListener class (in the com.ms.util.InputMethod package) is an interface class that includes methods for managing IMEs.

You must set the current IMM before activating an IME. The following code shows how to set the default IMM and install an IME.

InputManagerListener imm;
MyIME ime;

// Set default IMM
imm = com.ms.lang.SystemX.getDefaultInputManager ();
com.ms.lang.SystemX.setInputManager (imm, true);
if (imm != null)
{
    // Instantiate IME.
    ime = new MyIME () ;

    if (ime != null)
    {
        // Set IME to be current IME and activate it.
        imm.setInputMethod (ime);
        ime.activate ();
    }
}

Unicode Support

Although the Java language includes support for Unicode strings, many text editors use local character set encoding, and many text files contain local character set strings, not Unicode strings. This causes two different problems:

• At compile time, local character set encoded string literals must be converted to Unicode.
• At run time, strings must be converted between local character set encoding and Unicode during read and write operations.

The Microsoft Compiler for Java (jvc) translates local character set encoded string literals in Java source code to Unicode when it compiles the source into class files. When the Microsoft VM runs these class files, the string literals will appear correctly. The java.lang.Runtime methods getLocalizedInputStream and getLocalizedOutputStream will convert between local character set encoding and Unicode.

Note You should only use getLocalizedInputStream on input streams that are known to be encoded in a local character set. Do not use this method on input streams that contain Unicode characters.

Converting Local Encoding to Unicode

The getLocalizedInputStream method converts local character set encoding to Unicode. To use it, you must first call Runtime.getRuntime to get a Runtime object. Then, call the Runtime.getLocalizedInputStream method, passing the input stream object that you want to have converted. The getLocalizedInputStream method returns a DataInputStream object that performs local-character-set-to-Unicode conversion on the input stream. The following example demonstrates this technique.

Runtime rt = Runtime.getRuntime();
FileInputStream fisLoc;  // local
DataInputStream disUni;  // Unicode
String sInput;

fisLoc = new FileInputStream("LOCAL.TXT");
disUni = (DataInputStream)rt.getLocalizedInputStream(fisLoc);
sInput = disUni.readLine(); 

Converting Unicode to Local Encoding

The getLocalizedOutputStream method converts Unicode to local character set encoding. To use it, you must first call Runtime.getRuntime to get a Runtime object. Then, call the Runtime.getLocalizedOutputStream method, passing the output stream object that you want to have converted. The getLocalizedOutputStream method returns a DataOutputStream object that performs Unicode-to-local-character-set conversion on the output stream. The following example demonstrates this technique.

Runtime rt = Runtime.getRuntime();
FileOutputStream fosUni;  // Unicode
DataOutputStream dosLoc;  // local
String sOutput = "This is a Unicode string";

fosUni = new FileOutputStream("OUTPUT.TXT");
dosLoc = (DataOutputStream)rt.getLocalizedOutputStream(fosUni);
dosLoc.writeChars(sOutput);