Localization

In Java, any translatable text is generally stored in a set of localized property files called "resource bundles". The appropriate file is loaded at runtime for either the default locale or an explicitly selected non-default locale. While it is possible to use standard Java resource bundles in a Pivot application, Pivot adds support for JSON-based resource bundles that are slightly more flexible the built-in properties-based bundles. JSON resource bundles allow developers to more easily work with UTF-8 encoded resource strings, and also natively support hierarchical data, which can only be simulated when using properties files.

The following application provides a simple demonstration of localization in Pivot:

core wtk wtk-terra tutorials

The following resource bundles are provided; if your default system locale is among these, you should see a localized version of the application. Otherwise, the default locale ("en") will be used:

The resource bundle for the default locale is shown below:

The BXML source for the application is as follows. Note the use of the "%" prefix in the form label attributes. This prefix is known as the "resource resolution operator" in BXML. As the BXML is read, attribute values that begin with the "%" character are replaced by the corresponding values defined in the resource bundle:

function windowOpened(window) { window.requestFocus(); }
]]>

The Java source for the application is shown below:

properties) throws Exception { String language = properties.get(LANGUAGE_KEY); Locale locale = (language == null) ? Locale.getDefault() : new Locale(language); Resources resources = new Resources(getClass().getName(), locale); Theme theme = Theme.getTheme(); Font font = theme.getFont(); // Search for a font that can support the sample string String sampleResource = (String)resources.get("firstName"); if (font.canDisplayUpTo(sampleResource) != -1) { Font[] fonts = GraphicsEnvironment.getLocalGraphicsEnvironment().getAllFonts(); for (int i = 0; i < fonts.length; i++) { if (fonts[i].canDisplayUpTo(sampleResource) == -1) { theme.setFont(fonts[i].deriveFont(Font.PLAIN, 12)); break; } } } BXMLSerializer bxmlSerializer = new BXMLSerializer(); window = (Window)bxmlSerializer.readObject(Localization.class.getResource("localization.bxml"), resources); window.open(display); } @Override public boolean shutdown(boolean optional) { if (window != null) { window.close(); } return false; } @Override public void suspend() { } @Override public void resume() { } public static void main(String[] args) { DesktopApplicationContext.main(Localization.class, args); } } ]]>

The following example shows the application localized in German. Note that the applet is signed to allow the code to set the "user.language" system property:

core wtk wtk-terra tutorials de

Notice that the startup() method includes code to search for a font that can display a sample set of characters obtained from the "firstName" resource. This is because all fonts are not guaranteed to include support for all possible Unicode characters. If the current theme font is not capable of displaying the sample string, this block of code attempts to identify and set one that can. This code must be executed prior to constructing any user interface elements so that the correct font will be used.