The basics

Best Practices

1. Follow the standards described in this guide
2. Always use properties files for user interface text; never include displayable text in java, jsp, or templates (see Localizing Tools below)
3. Use properties files only for user interface text and config files for configuration settings (see Config Properties below).
4. 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
5. Group keys by view, ie. edit.title, edit.instructions, list.title, list.instructions, create.title, etc
6. Never use displayable text when executing comparisons within the logic of the tool (separate codified values from displayable text)
7. 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).
8. 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)
9. All numbers and dates should be formatted specific to the user's locale (e.g. java.text.NumberFormat and java.text.DateFormat)
10. Test tools in more than one language

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");