Best Practices for Internationalized Tools in Sakai

This document describes how to write Sakai tools that are localized and internationalized.

1 Best Practices
2 Localizing Tools
3 Structure messages appropriately
4 Localize Date & Time
5 Config Properties
6
7 ResourceLoader Class
- 7.1 JSF based tools
- 7.2 JSP based tools
- 7.3 Velocity based tools
- 7.4 Javascript based tools
- 7.5 RSF based tools
- 7.6 GWT (Google Web Toolkit) based tools
- 7.7 Wicket based tools
- 7.8 Trimpath based tools
8 Suggested reading
- 8.1 Introducing inheritance to PropertyResourceBundles

Best Practices

Follow the standards described in this guide
Always use properties files for user interface text; never include displayable text in java, jsp, or templates (see Localizing Tools below)
Use properties files only for user interface text and config files for configuration settings (see #Config Properties below).
Use a proper naming schema for keys in your resource bundles. The name of the keys should provide some information about the context of the displayed text. This helps the translators during the translation process. A naming schema could be <view>.<type>.<name>. Examples: edit.button.save, edit.label.title or list.action.addnew
Group keys by view, ie. edit.title, edit.instructions, list.title, list.instructions, create.title, etc
Never use displayable text when executing comparisons within the logic of the tool (separate codified values from displayable text)
Always use the ResourceLoader (not ResourceBundle) class for retrieving properties values, and invoke ResourceLoader methods dynamically, to accommodate dynamic user preferences (see Resource Loader below).
All dynamically constructed phrases must be sensitive to locale specific subject/verb/object ordering by using the Sakai ResourceLoader class: org.sakaiproject.util.ResourceLoader.getFormattedMessage() (see Structure messages appropriately below)
All numbers and dates should be formatted specific to the user's locale (e.g. java.text.NumberFormat and java.text.DateFormat)
Test tools in more than one language

Localizing Tools

All language based text should be localized into a properties file (e.g. Messages.properties), specific to each tool. This includes static text rendered from JSF/RSF/Velocity/etc. templates, and dynamic text inserted from the tool classes.

For example:

page.message.key = This is a message which the user will see

Standard Java formatting classes, such as MessageFormat, ChoiceFormat, DateFormat, NumberFormat and DecimalFormat are preferred over tool-specific formatting, which may not be sensitive to international formats. The org.sakaiproject.util.ResourceLoader class provides getFormattedMessage (wrapper for MessageFormat) and getLocale methods to assist in formatting.

There is an excellent tutorial on internationalization at http://java.sun.com/docs/books/tutorial/i18n/index.html as well as a checklist at http://java.sun.com/docs/books/tutorial/i18n/intro/checklist.html.

Beginning in Sakai 2.9, the citations helper will use a new way of configuring search sources in its config.xml file (which is loaded dynamically from a resources folder in the citations-admin site). This is done so changes can be made at run-time rather than at compile-time or startup-time. The config.xml file includes strings that should be internationalized. The format of that file is described in the I18N for Citations Helper in Sakai 2.9.

Structure messages appropriately

Don't split a simple statement across multiple messages in order to place variables in the message. Different languages use different subject/verb/object sentence constructs. The org.sakaiproject.util.ResourceLoader.getFormattedMessage() method will format variable text based on a user's preferred locale (using the same arguments defined by the java.util.MessageFormat class):

Example Final Statement:
Welcome to the awesome view, Mr. User.

Wrong Way:

page.statement.1 = Welcome to the
page.statement.2 = view,

Right Way:

# Sample: Welcome to the (page title) view, (user display name).
page.statement = Welcome to the {0} view, {1}

Localize Date & Time

Here's an example of creating a DateFormat object to format a date according to local conventions:

DateFormat df = DateFormat.getDateInstance( DateFormat.SHORT, (new ResourceLoader()).getLocale() );

Here's an example of creating a DateFormat object to format a date according to local conventions, and extracting the pattern string for later use:

DateFormat df = DateFormat.getDateInstance( DateFormat.SHORT, (new ResourceLoader()).getLocale() );
date_entry_format_description = ((SimpleDateFormat)df).toPattern();

Config Properties

Properties files (<filename>.properties) should only be used for user interface text that should be translated. All other configuration information (e.g. configuration constants, class names, filenames, etc.) should be in a separate directory tree. Alternately, config files can use the <filename>.config extension and be referenced as follows:

import java.util.Properties;
...
Properties p = new Properties();
p.load(this.getClass().getResourceAsStream("filename.config"));

ResourceLoader Class

The org.sakaiproject.util.java.ResourceLoader class is a wrapper class for the ResourceBundle class. It provides dynamic language/locale support for individual users, and is recommended for all Sakai tools.

The sakai-util.jar file (or sakai-util-java.jar file prior to Sakai 2.2) needs to be included with every tool during the maven build process, by including the following dependency in the tool's project.xml file:

<dependency>
<groupId>org.sakaiproject</groupId>
<artifactId>sakai-util</artifactId>
<version>${sakai.version}</version>
<properties>
<war.bundle>true</war.bundle>
</properties>
</dependency>

Since Sakai 2.6 (Kernel 1.0+), this is now sakai-kernel-util:

<dependency>
    <groupId>org.sakaiproject.kernel</groupId>
    <artifactId>sakai-kernel-util</artifactId>
</dependency>

Strings in the tool's properties file can be retrieved in the Java code using the ResourceLoader class:

ResourceLoader rb = new ResourceLoader("_org.sakaiproject.tool.foobar.bundle.Messages_");
String foo = rb.getString("foo");

JSF based tools

Each tool's properties file should be loaded as a managed-bean in it's faces-config.xml file:

<managed-bean>
      <description>
         Dynamic Resource Bundle Loader
      </description>
      <managed-bean-name>msgs</managed-bean-name>
      <managed-bean-class>org.sakaiproject.util.java.ResourceLoader</managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
      <managed-property>
         <description>Bundle baseName</description>
         <property-name>baseName</property-name>
         <value>_org.sakaiproject.tool.foobar.bundle.Messages_</value>
      </managed-property>
</managed-bean>

An alternative to modifying the faces-config.xml file is to insert the following into the jsf file:

<jsp:useBean id="msgs" class="org.sakaiproject.util.ResourceLoader" scope="session">
   <jsp:setProperty name="msgs" property="baseName" value="_org.sakaiproject.tool.foobar.bundle.Messages_"/>
</jsp:useBean>

Any reference to <f:loadBundle> should be removed from all JSF template files.

Localized strings in properties files are referenced using standard JSF variable syntax:

<h:outputText value="#{msgs.foo}"/>

If you have parameters, you should use the practice of putting these in the messages like the other methods and using outputFormat for format them. The first parameter will go in {0} and the second in {1}, etc.

<h:outputFormat value="#{authorMessages.cert_rem_assmt}" escape="false">
   <f:param value="#{publishedassessment.title}"/> 
</h:outputFormat>

JSP based tools

The ResourceLoader can be initialized by inserting the following into the jsp file:

<jsp:useBean id="msgs" class="org.sakaiproject.util.ResourceLoader" scope="request">
   <jsp:setProperty name="msgs" property="baseName" value="_org.sakaiproject.tool.foobar.bundle.Messages_"/>
</jsp:useBean>

If the bean is defined as above, localized strings in properties files can be referenced using standard JSP variable syntax:

<c:out value="${msgs.foo}"/>

JSTL <fmt:setLocale> and <fmt:setBundle> should not be necessary for <fmt:message> to work, but with Spring MVC, a localeResolver bean must be registered to handle proper system/site/user settings. An example of this is implemented for metaobj and OSP (SakaiLocaleResolver). Note that it could be moved to somewhere like sakai-kernel-util if others need it; send a message to sakai-dev if this is the case. The localeResolver bean can be set in web-config.xml like this: