Widget Internationalization

Not all localization is handled automatically by the internationalization features of the CDEJ. Widgets may have specific localization requirements that are not covered by the CDEJ and the widget developer must internationalize the widget to accommodate these. The main internationalization issues of concern to the widget developer are:

accessing and rendering localized text values;
referencing localized versions of images or icons;
providing locale information and localized text elements to JavaScript code used by a widget in the web browser;
laying out content on the HTML page in a way that can accommodate the increased length of text when localized into other languages.

Accessing Data with Paths provides details on how to construct paths that identify localized text properties resources on the classpath or in the Application Resource Store and to resolve these paths to the localized text values. Examples of this process are also provided in that appendix. Once retrieved, the localized text can be incorporated into the HTML mark-up produced by a renderer plug-in class.

Localized images are often required where the images contain text or other symbols that are specific to one language or culture. The developer should avoid including text in images where possible. It makes the application harder and more expensive to localize and also affects the accessibility of the application. Accessibility Concerns describes how applications are often required to be accessible to as many people as possible. People with visual impairments may find that text in images is difficult to read or entirely unreadable. Nevertheless, internationalizing such elements is a simple process. The HTML produced by the widget's renderer plug-in class includes a img element with a src attribute that references an image resource on the application server. These image resources can be added to the WebContent folder of an application component. A simple scheme to support internationalization then places image files in sub-folders named for the locales. For example, create an images folder within the WebContent folder. Create folders named en (English) and es (Spanish) within that images folder. Now place the localized image files for English and Spanish into their respective locale folders. Within the renderer, the localized image can be referenced as shown in the example below. The context of the example is the render method of a renderer plug-in class.

Figure 1. Referencing Localized Image Files

Element img = fragment.getOwnerDocument().createElement("img");
img.setAttribute("src",
    "../images/" + getLocale().toString + "/icon.png");

The getLocale method returns the locale of the active user, so the image source URI could be generated as, for example, ../images/en/icon.png for a user in the English locale and ../images/es/icon.png for the Spanish locale. Alternatively, the locale folder could be omitted and the locale could could appear in the image file name.

A problem with this scheme is that a user with a locale en_US will not seen any image, as there is no en_US folder within the images folder. For text properties, a locale fall-back scheme is used, but that does not apply in the example above. There are a number of ways to accommodate extra locales:

create one folder for each supported locale and place the localized images in those folders, even if the image is the same for several locales, such as if en, en_US and en_GB were supported simultaneously and there were no spelling variations across those locales for the words used in the images;
for each image, define a property in a localized text properties resource containing the path to image appropriate for the locale of that properties resource. Instead of constructing the path in the renderer, resolve the text property that contains the path and use that. This scheme is similar to the use of the Images.properties file in UIM development described in the Cúram Web Client Reference Manual and allows the normal locale fallback mechanism to operate. (An overview of this fallback mechanism is provided in Accessing Data with Paths.)

There is a separate type of text-based image generation and localization feature in the CDEJ that is described in the Cúram Web Client Reference Manual. It is not directly related to widget development.

Widgets that depend on JavaScript libraries and scripts may require that the JavaScript be internationalized. The two main requirements are to supply the JavaScript code with the correct locale to ensure that localization features of the JavaScript library are used correctly and/or to supply localized text elements to the JavaScript routines. The specific requirements vary between widgets and are beyond the scope of this guide. However, the basic approach for the widget developer is to generate JavaScript content containing the required information from locale information and localized text values available to the renderer plug-in class. For example, the renderer plug-in can generate a script containing a class to a JavaScript function that passes the value of the active user's locale. The locale value is embedded in the function call in a same way it was embedded in the image URI in Widget Internationalization, by calling getLocale and converting it to a string. Localized text elements retrieved by the renderer plug-in class can also be embedded into a script, perhaps into a JavaScript array or object, depending on requirements.

The layout of a page may also be affected by localization requirements. The text of a label in one language may become much longer when translated into another language. An average of 30% more space should be added for any English text to accommodate the replacement of that text with text in other languages. However, depending on the language and the phrase, the text could be require twice the amount of space or even more.