Adding Languages

This chapter describes how to add a language to a Web Center application. It shows which files must be translated and gives some guidelines that must be followed during translation.

The chapter also describes how to add the new language to the language chooser and how to define the new language as the default language.

This chapter does not cover localizable items that are just used by Web Center but are localized in other components like the DirX Identity database; for example, descriptions and attribute names of request workflow tasks.

Overview

Files to Be Translated

The list of files to be translated includes:

An HTML file displayed when the browser’s Javascript support has been disabled.
A Javascript message file messages.js
A Java properties file text.properties
HTML snippets with extension html
JSP snippets with extension jsp
Pages displayed in cases of severe errors.

The following figure shows the files and their locations within a Web Center application:

resources
    build
        html
            noscript.html
        messages
            <language>
                 messages.js

WEB-INF
    classes
        resources
            languages
                <language>
                    text.properties
                    *.html
                    *.jsp
                    <any subfolder, recursively>
                        *.html
                        *.jsp

WEB-INF
    jsp
        view
            error
                errorMessages.txt
                forbidden.html
                severeErrorPage.html

Often, you don’t have to translate all the files listed here. You can especially spare those subfolders of WEB-INF/classes/resources/languages/<language> that relate to types of objects you don’t support in your application.

If, for example, you don’t use business objects, you can ignore the files in folder WEB-INF/classes/resources/languages/<language>/bo.

How to Proceed

To prepare and execute translation:

Identify the ISO 639 alpha-2 or alpha-3 code of your new language.You can find the codes on the Internet.Examples are it for Italian and nl for Dutch.
Copy the two language folders for an existing language to new folders for your new language.For example, copy resources/build/messages/en to resources/build/messages/nl and WEB-INF/classes/resources/languages/en to WEB-INF/classes/resources/languages/nl.
Save a backup of the files that must be directly modified.These files are listed in the previous step and are located in the folder resources/build/html and in folder WEB-INF/jsp/view/error.
Translate each message file as described in the next section.
Configure the language chooser and, if applicable, set the default language to your new language.

Translating Files

Message Files

File messages.js

The Javascript file messages.js contains message texts evaluated directly by the browser.

The first definition assigns the actual language code to the attribute language of the message object.Set the value to the code of your new language, like

messages.languages = "nl";

for Dutch.

The main section “messages.texts” contains a hierarchical number of message sections represented in JSON format. Each object is enclosed in curly braces and contains a list of attribute value pairs. A value is either of a basic Javascript type like String, Number or Boolean, or again a JSON object. Attribute and value are separated by a colon. If the attribute contains spaces or matches a Javascript reserved name like true or false, it must be enclosed in single or double quotes. Otherwise, the quotes are optional. Separate successive attribute value pairs within a section by a comma, but take care not to add a comma after the last attribute value pair within a section.

The section “messages.custom.texts” is used to define custom alternatives for the texts in “messages.texts”. The texts are usually not customized here but in separate custom files.

Don’t change the attributes since they are used to access the message texts in other Javascript files. Just translate the values into your new language.

Each double quote with a value must be escaped with a backslash. Non-ASCII characters in the values must be replaced with their Unicode representations.

nonASCII: "A value with umlaut: \u00F6.",
quoted: "A \"quoted\" value",

The file is located in the folder *resources/build/messages/*language.

Use the translation utilities delivered with Web Center to translate the message file without having to manually replace non-ASCII characters with their Unicode representations. The utilities are described below.

File text.properties

The Java properties file text.properties contains message texts evaluated on the server side.

Each message consists of a key and a text, separated by an equality character. The keys are fixed and mustn’t be changed. Non-ISO-8859-1 characters in the texts must be replaced with their Unicode representations.

The file is located in folder WEB-INF/classes/resources/languages/<language>.

Use the translation utilities delivered with Web Center to translate the properties file without having to manually replace non-ISO-8859-1 characters with their Unicode representations. The utilities are described below.

Snippets

Each language directory contains a set of HTML snippets (extension .html) and JSP snippets (extension .jsp). Each snippet defines the introductory text that is displayed at the top of the application-specific section of a Web Center page. The text briefly describes the data that is displayed on the page, or the functionality provided by the page. There’s usually a separate snippet per object type (like user, role and password policy) and per function (like list, summary and modify).

By default, the snippets are read from the local file system using the default file encoding of the Java version. This will usually not work correctly for snippets containing non-ASCII characters. That’s why the English and German snippets use HTML references for non-ASCII characters, like “ä” for “ä”. This is of course inconvenient especially for languages with character sets quite different from ASCII.

JSP Snippets

JSP snippets contain HTML code and JSP code that inserts some dynamic content into the page, like the value of a configuration parameter.

When translating a JSP snippet into another language, create and store the snippet in UTF-8 encoding, and add a metatag-instruction at the beginning of the file specifying the encoding used. Then you can use any character that can be UTF-8 encoded, as shown in the following sample:

<%@ page pageEncoding="UTF-8" %>
<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c" %>

<h2 class="headlineText">
    Welcome to DirX Identity Web Center
    ÄÖÜ – αβγ – йкл – フヨヰ
</h2>

Don’t change any JSP code in the snippets.

HTML Snippets

HTML snippets contain pure HTML code. The snippet encoding is not defined in the HTML snippets itself but per language in file webCenter.properties:

resources.html.fileEncoding.de = ISO-8859-1
resources.html.fileEncoding.en = ISO-8859-1
resources.html.fileEncoding.ja = UTF-8

When translating HTML snippets into another language, add a configuration parameter for that language with an appropriate encoding. Then create and store the snippets in the specified encoding.

Error Pages

The error pages are displayed in cases of severe errors where even the end user’s language sometimes cannot be detected. Therefore, there isn’t one error page per language. Instead, each page displays a message in all the supported languages.

File noscript.html

This file is displayed when the browser’s Javascript support is disabled.

<h2 class="headlineText" style="color:red;margin-top:50px">
    The requested page cannot be displayed since Javascript is disabled in your browser!
</h2>
<h2 class="headlineText" style="color:red;margin-top:25px">
    Die angeforderte Seite kann nicht angezeigt werden, da Javascript in Ihrem Browser deaktiviert ist!
</h2>

Just add a new HTML <h2 class="headlineText"> element with a corresponding text in the new language to the HTML body.

The message text is HTML code. Replace any special and any non-ASCII character with its corresponding HTML reference.

The file is located in folder resources/build/html.

File errorMessages.txt

This file is used when processing a request fails for a severe reason. The error page tries to display a message in the end user’s preferred language.

<%
    messages.put("de","Ihre Anfrage konnte nicht bearbeitet werden.");
    messages.put("en","Your request could not be processed.");

    defaultLanguage = "en";
%>

The file contains some Java code that fills a message map with name “messages”. Just put a new message with the code of the new language as key and the corresponding message text as value into the map.

The message text is a Java string. Escape each double quote within the text with a backslash, and replace any non-ASCII character with its Java Unicode character representation, like in

messages.put("en",
    "A \"quoted\" message with an umlaut \u00e4.");

The file is located in folder WEB-INF/jsp/view/error.

File forbidden.html

This file is displayed if access to a Web Center page has been rejected for security reasons.

<body>
    <h1>Access to the requested resource has been forbidden.</h1>
    <h1>Der Zugriff auf die angeforderte Seite wurde abgelehnt.</h1>
</body>

Just add a new HTML <h1> element with a corresponding text in the new language to the HTML body.

The message text is HTML code. Replace any special and any non-ASCII character with its corresponding HTML reference.

The file is located in folder WEB-INF/jsp/view/error.

File severeErrorPage.html

This file is displayed as a last resort when processing a request fails such that a user-friendlier and less disruptive page cannot be displayed.

<td colspan="3" class="leftContent" style="…">
    <h2 class="headlineText">Your request could not be processed.</h2>
    <h2 class="headlineText">Ihre Anfrage konnte nicht bearbeitet werden.</h2>
</td>

Just add a new HTML <h2 class="headlineText"> element with a corresponding text in the new language to the HTML body.

The message text is HTML code. Replace any special and any non-ASCII character with its corresponding HTML reference.

The file is located in the folder WEB-INF/jsp/view/error.

Character Representations

HTML Code

In HTML code, you can use any ASCII character. Some characters, however, have a special meaning in HTML and should be replaced with their corresponding HTML entity references to avoid misinterpretations.

Table 1. HTML Entity References for Special HTML Characters
Character	HTML Entity Reference
Double quote: “	"
Ampersand: &	&
Less than: <	<
Greater than: >	>

You can also use non-ASCII Unicode characters like umlauts, Greek and Cyrillic characters, and characters from Asian languages. These characters must also be replaced with their corresponding HTML entity or numeric references.

Table 2. HTML References for Sample non-ASCII Characters
Character	HTML Entity Reference	Numeric Reference
ä	ä	ä
ö	ö	ö
ü	ü	ü
Ä	Ä	Ä
Ö	Ö	Ö
Ü	Ü	Ü
ß	ß	ß

For a complete list of HTML numeric references, see the file install_path/web/webCenter-domain/tools/TranslationUtilites/files/HTMLNumericReferences.html.

Samples

<h1>This is a &quot;quoted&quot; message.</h1>
<h1>This is a text with the greek letter gamma &#x393; and an umlaut &auml;.</h1>

Java and JSON Unicode Character Representations

Replace any non-ASCII character within a Java String or JSON value with its Unicode escape sequence, which is “\u”, followed by the 4-digit hexadecimal character value. Alphabetic hex digits (“a” - “f”) can be either lower case or upper case.

Table 3. Unicode Character Representation for Sample non-ASCII Characters
Character	Unicode Representation
ä	\u00e4
ß	\u00df
Γ	\u0393
Δ	\u0394
Б	\u0411
Д	\u0414
ก	\u0e01
ข	\u0e02

For a complete list of Unicode character representations, see file install_path*/web/webCenter-domain/tools/TranslationUtilites/files/JavaUnicodeCharacterRepresentations.html.

Sample

"This is a string with the greek letter gamma \u0393; and an umlaut \u00e4."

Translation Utilities

When translating a message file into a new language, you probably don’t want to manually replace all non-ASCII or non-ISO-8859-1 characters with their substitutes. It’s much more convenient to enter the message texts as usual, for example in an editor that supports UTF-8, and then automatically generate a message file with correct substitutions. Web Center delivers some Windows batch scripts that convert message files from ASCII or ISO-8859-1 to UTF-8 (or any other encoding), and vice versa. The scripts are based on the JDK utility native2ascii.exe, so you need a JDK (not just a JRE).

The scripts are located in the folder install_path/web/webCenter-domain/tools/TranslationUtilites/bin. Use the scripts in subfolder text.properties to translate text.properties files and the ones in subfolder messages.js to translate messages.js files.

First, fix the JDK path and choose your preferred encoding for editing in file setEnv.bat. The predefined encoding is “utf-8”, which is supported, for example, by Notepad and jEdit.

text.properties

To translate a text.properties file, proceed as follows:

Change to subfolder text.properties.
Copy your original text.properties file into the folder (overwriting the delivered sample file).
Run script createEditableFile.bat. The script creates file text-editable-encoding.properties. In the file name, encoding is replaced with the selected encoding, like “utf-8”.
Open the created file in a suitable editor and then translate the message texts. When finished, save the file.
Run script createWebCenterFile.bat. The script creates file text-WebCenter.properties. Check if the special characters have been correctly replaced.
Copy the file text-WebCenter.properties to its destination folder within your Web Center application, renaming it back to text.properties.

messages.js

To translate a messages.js file, proceed as follows:

Change to the subfolder messages.js.
Copy your original messages.js file into the folder (overwriting the delivered sample file).
Run the script createEditableFile.bat.The script creates file messages-editable-encoding.js.In the file name, encoding is replaced with the selected encoding, like “utf-8”.
Open the created file in a suitable editor and then translate the message texts.When finished, save the file.
Run the script createWebCenterFile.bat.The script creates file messages-WebCenter.js.Check if the special characters have been correctly replaced.
Copy the file messages-WebCenter.js to its destination folder within your Web Center application, renaming it back to messages.js.

Configuration Tasks

Extending the Language Chooser

To add a new language to the language chooser that is displayed in the header section of each Web Center page, add the language code and its display label to the message with key “application.option.language“ in the message file text.properties.Do this for each supported language.

application.option.languages = en:English;de:Deutsch;nl:Dutch

Changing the Default Language

The default language is defined in file WEB-INF/web.xml by configuration parameter javax.servlet.jsp.jstl.fmt.fallbackLocale. To change the default language, just assign the new language code.

javax.servlet.jsp.jstl.fmt.fallbackLocale = nl

How a User’s Language is Determined

When a user starts a Web Center session, Web Center applies the following rules with descending priority in order to determine the user’s language:

The request includes a Web Center language cookie and the language specified in the cookie is valid.
The request includes an Accept-Language header and one of the requested languages is valid. The languages in the header are evaluated according to their quality factors. The browsers usually let a user define his preferred languages via a configuration option.
The default language.

The language is stored in the user’s session and holds throughout the session unless the user chooses another language from the language chooser.

Web Center also tries to persistently store the language in a browser cookie (the language cookie) for subsequent sessions. But since browser cookies are not reliable, the language chosen for one session may be lost until the next session.