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 ‘ResourceBundle’s. There are two formats of ‘ResourceBundle’s:
‘.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.
1. 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.
2. The ‘gnu.gettext.GettextResource’ API.
Reference documentation in Javadoc 1.1 style format is in the
javadoc2 directory (javadoc2/index.html).
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.