Gettext/Java

15.5.3 Java

RPMs: java, java2
Ubuntu packages: default-jdk
File extension: java
String syntax: "abc", """text block"""
gettext shorthand: i18n("abc")
gettext/ngettext functions: GettextResource.gettext, GettextResource.ngettext, GettextResource.pgettext, GettextResource.npgettext
textdomain: —, use ResourceBundle.getResource instead
bindtextdomain: —, use CLASSPATH instead
setlocale: automatic
Prerequisite: —
Use or emulate GNU gettext: —, uses a Java specific message catalog format
Extractor: xgettext -ki18n
Formatting with positions: MessageFormat.format "{1,number} {0,number}" or String.format "%2$d %1$d"
Portability: fully portable
po-mode marking: —

Before marking strings as internationalizable, uses of the string concatenation operator need to be converted to MessageFormat applications. For example, "file "+filename+" not found" becomes MessageFormat.format("file {0} not found", new Object[] { filename }). Only after this is done, can the strings be marked and extracted.

GNU gettext uses the native Java internationalization mechanism, namely ResourceBundles. There are two formats of ResourceBundles: .properties files and .class files. The .properties format is a text file which the translators can directly edit, like PO files, but which doesn’t support plural forms. Whereas the .class format is compiled from .java source code and can support plural forms (provided it is accessed through an appropriate API, see below).

To convert a PO file to a .properties file, the msgcat program can be used with the option --properties-output. To convert a .properties file back to a PO file, the msgcat program can be used with the option --properties-input. All the tools that manipulate PO files can work with .properties files as well, if given the --properties-input and/or --properties-output option.

To convert a PO file to a ResourceBundle class, the msgfmt program can be used with the option --java or --java2. To convert a ResourceBundle back to a PO file, the msgunfmt program can be used with the option --java.

Two different programmatic APIs can be used to access ResourceBundles. Note that both APIs work with all kinds of ResourceBundles, whether GNU gettext generated classes, or other .class or .properties files.

The java.util.ResourceBundle API.

In particular, its getString function returns a string translation. Note that a missing translation yields a MissingResourceException.

This has the advantage of being the standard API. And it does not require any additional libraries, only the msgcat generated .properties files or the msgfmt generated .class files. But it cannot do plural handling, even if the resource was generated by msgfmt from a PO file with plural handling.
The gnu.gettext.GettextResource API.

Reference documentation in Javadoc 1.1 style format is in the javadoc2 directory.

Its gettext function returns a string translation. Note that when a translation is missing, the msgid argument is returned unchanged.

This has the advantage of having the ngettext function for plural handling and the pgettext and npgettext for strings constraint to a particular context.

To use this API, one needs the libintl.jar file which is part of the GNU gettext package and distributed under the LGPL.

Four examples, using the second API, are available in the examples directory: hello-java, hello-java-awt, hello-java-swing, hello-java-qtjambi.

Now, to make use of the API and define a shorthand for ‘getString’, there are three idioms that you can choose from:

(This one assumes Java 1.5 or newer.) In a unique class of your project, say ‘Util’, define a static variable holding the ResourceBundle instance and the shorthand:
```
private static ResourceBundle myResources =
  ResourceBundle.getBundle("domain-name");
public static String i18n(String s) {
  return myResources.getString(s);
}
```
All classes containing internationalized strings then contain
```
import static Util.i18n;
```
and the shorthand is used like this:
```
System.out.println(i18n("Operation completed."));
```

In a unique class of your project, say ‘Util’, define a static variable holding the ResourceBundle instance:

public static ResourceBundle myResources =
  ResourceBundle.getBundle("domain-name");

All classes containing internationalized strings then contain

private static ResourceBundle res = Util.myResources;
private static String i18n(String s) { return res.getString(s); }

and the shorthand is used like this:

System.out.println(i18n("Operation completed."));

You add a class with a very short name, say ‘S’, containing just the definition of the resource bundle and of the shorthand:

public class S {
  public static ResourceBundle myResources =
    ResourceBundle.getBundle("domain-name");
  public static String i18n(String s) {
    return myResources.getString(s);
  }
}

and the shorthand is used like this:

System.out.println(S.i18n("Operation completed."));

Which of the three idioms you choose, will depend on whether your project requires portability to Java versions prior to Java 1.5 and, if so, whether copying two lines of codes into every class is more acceptable in your project than a class with a single-letter name.