File: gettext.info,  Node: Java,  Next: C#,  Prev: Python,  Up: List of Programming Languages

16.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.