Localization and Internationalization with StringTemplate
Localization and Internationalization with StringTemplate
January 27, 2006
Terence Parr
parrt at cs.usfca.edu
WARNING: this example uses a pre-release version of StringTemplate
2.3, which allows the $strings.page1_title$ references used
in this example. 2.3 should be out in February 2006. I include a
link to a pre-release version at the bottom of this article.
StringTemplate provides a simple and effective method for localizing
web pages. The goal is to alter a page based upon the locale; that
is, page strings or other content must change depending on a locale.
This article not only illustrates how to make a pages change text
depending on locale, it shows how the same site may easily have two
different skins (site "looks").
This technique works well in practice for real sites. Schoolloop.com is a case
in point. Click on the link that says "en espanol" to flip the
site into Spanish mode. The exam same templates are used; all strings
are pulled from a serious of resource bundles. There is no
duplication of pages to change the strings.
Multiple skins
First let's look at multiple skins in order to show how templates are
loaded for this example.
Multiple site looks are organized into their own directories. A
StringTemplateGroup object rooted at that directory will load
templates directly from there. In my example, I made two skins, blue
and red. Here is how the group is loaded:
String skin="blue";
ClassLoader cl = Thread.currentThread().getContextClassLoader();
// get a template group rooted at appropriate skin
String absoluteSkinRootDirectoryName = cl.getResource(skin).getFile();
StringTemplateGroup templates =
new StringTemplateGroup("test", absoluteSkinRootDirectoryName);
Then, when you ask for an instance of a page, it pulls from whichever
directory skin is set to:
StringTemplate page1ST = templates.getInstanceOf("page1");
Here is page 1 in the blue skin:
<html>
<title>$strings.page1_title$</title>
<body>
<font color=blue>
<p>$strings.intro$
<p>$strings.page1_content$
</font>
</body>
<html>
and here is page 2:
<html>
<title>$strings.page2_title$</title>
<body>
<font color=blue>
<p>$strings.page2_content$
</font>
</body>
<html>
For the red, here is page 1:
<html>
<title>$strings.page1_title$</title>
<body>
<font color=red>
<h1>$strings.page1_title$</h1>
<p>$strings.intro$
<hr>
<p>$strings.page1_content$
</font>
</body>
<html>
and page 2:
<html>
<title>$strings.page2_title$</title>
<body>
<font color=red>
<h1>$strings.page2_title$</h1>
<hr>
<p>$strings.page2_content$
</font>
</body>
<html>
The thing to note is that there is no text, just formatting in these
page templates. Those strings from the strings attribute are
used for all text that could change per locale.
Localizing template strings
Once the code knows how to load templates, the locale must dictate
which strings are displayed. The templates clearly have attribute
references pulling from a strings table (a hash table). For this
example, I'm assuming that I have a few different strings and that I'm
storing them in a Java properties file called
language.strings where language is the
two-letter language code. Here is my en.strings file:
intro=Welcome to my test page for internationalization with StringTemplate
page1_title=Page 1 testing I18N
page2_title=Page 2 testing I18N
page1_content=This is page 1's simple page content
page2_content=This is page 2's simple page content
and here is my fr.strings file:
intro=Bienvenue a mon page de test pour internationalization avec StringTemplate
page1_title=Page 1 test de I18N
page2_title=Page 2 test de I18N
page1_content=Le content du page 1
page2_content=Le content du page 2
To load these per the current locale is pretty easy:
// use Locale to get 2 letter country code for this computer
Locale locale = Locale.getDefault();
String defaultLanguage = locale.getLanguage();
// allow them to override language from argument on command line
String language = defaultLanguage;
if ( args.length>0 ) {
language = args[0];
}
// load strings from a properties files like en.strings
URL stringsFile = cl.getResource(language+".strings");
if ( stringsFile==null ) {
System.err.println("can't find strings for language: "+language);
return;
}
Properties strings = new Properties();
InputStream is = stringsFile.openStream();
strings.load(is);
The strings properties object is just a Hashtable so
you can directly pass to StringTemplate templates as an attribute:
StringTemplate page1ST = templates.getInstanceOf("page1");
page1ST.setAttribute("strings", strings);
To generate the page, just say:
System.out.println(page1ST);
The output will be (for the en locale):
<html>
<title>Page 1 testing I18N</title>
<body>
<font color=blue>
<p>Welcome to my test page for internationalization with
StringTemplate
<p>This is page 1's simple page content
</font>
</body>
<html>
If I change the locale to fr then without changes templates,
the following is generated:
<html>
<title>Page 1 test de I18N</title>
<body>
<font color=blue>
<p>Bienvenue a mon page de test pour internationalization avec
StringTemplate
<p>Le content du page 1
</font>
</body>
<html>
Not sure "content" translates to French as "content" (heh, doesn't
that mean "happy"?).
Source and compilation
Here is the Java code, different strings, and different skins:
Here is the pre-release 2.3b5
jar needed to compile this example.
You naturally need ANTLR too; get it here.
You can compile this example like this:
javac -classpath .:antlr-2.7.6.jar:stringtemplate-2.3b5.jar Test.java
java -classpath .:antlr-2.7.6.jar:stringtemplate-2.3b5.jar Test
Summary
In summary, the key element to demonstrate here is that you do not
have to duplicate all of your templates to change what they say. You
can leave the formatting alone and, with a simple hashtable pulled
from a data file, push in the proper strings per the locale. I also
took the opportunity to show off just how easy it is to make multiple
site skins.
