Module org.tquadrat.foundation.i18n

Package org.tquadrat.foundation.i18n

package org.tquadrat.foundation.i18n

An API for the localisation ("l10n", although this abbreviation is rarely used) or internationalisation ("i18n") of an application (and, with some limitations, of a library). It provides annotations that allows to have multiple translations for a text directly in the source code. The annotation processor component provided with the project org.tquadrat.foundation.i18n.ap externalises these texts to regular resource bundle properties files.

For the configuration of the annotation processor, refer to the documentation for that project.

Internationalisation of Texts and Messages

In Java, localisation or internationalisation is usually done by using an instance of ResourceBundle that is retrieved by a call to ResourceBundle.getBundle(String). It will load the texts for the currently active Locale (see Locale.getDefault()).

There are several possible sources for the texts itself, but the most commonly used are Java properties files named following a special naming convention; for the file format refer to Properties.

The challenge is to update these properties files in parallel to writing the code, ensuring that the texts are really there when needed.

As a solution, this library provides two annotations (plus three helper annotations) that are processed by an annotation processor to create the resource bundle properties files during compilation.

The Annotations for the I18N feature

The internationalisation feature provides six annotations in total:

• @BaseBundleName
• @Message
• @MessagePrefix
• @Text
• @Translation
• @UseAdditionalTexts

The annotations @BaseBundleName and @MessagePrefix are used to configure the generation process, and @UseAdditionalTexts provides the location for additional texts (refer to respective chapter below, while the remaining three do define a text or a message.

The semantic differentiation between a Textand a Message is just high-handed: the assumption is that a message can be used freely at various locations in the code, while a text is unique for just one single context. This is reflected in the respective annotations.

@BaseBundleName

This annotation has to be applied to a String constant that holds the base bundle name; that name is basically a fully qualified Java class name, but it is not required (not even wanted) that this class exists.

The annotation has two attributes:

String defaultLanguage

This is the ISO 639-1two-letter-code for the default language; the resource bundle for this language is used when there is none for the current language or locale. Although it is said "language", the value could be also a full fledged locale.

The default value, that is used when the annotation was not applied, is "en".

boolean createResourceBundleProvider

As the properties files for the resource bundles are resources that are now local to a module, a service is required to expose the resource bundle to other modules. This is done through an instance of ResourceBundleProvider.

This flag controls whether the annotation processor will generate such a resource bundle provider; the default isfalse.

If this annotation is not used at all, the constant "MessagesAndTexts" will be used for the base bundle name, the locale ENGLISH is used as the default language and no resource bundle provider will be generated by the annotation processor.

The use of this annotation may look like this:

  …
  /**
   *  The base bundle name.
   */
  @BaseBundleName( defaultLanguage = "de", createResourceBundleProvider = false )
  public static final String m_BaseBundleName = "com.test.Messages";
  
  …

When you are using the translations for German (de) and English (en), the annotation processor will generate the properties files com/test/Messages.properties (containing the German texts and being the default or fallback resource) and com/test/Message_en.properties (with the English texts).

@MessagePrefix

The keys for messages are numbers or short Strings that will be prefixed with the value of the String that is annotated with this annotation. That value should somehow identify the source module so that the origin of the message can be identified easily when it shows up on the user's screen.

The annotation is used as in the sample below:

  …
  /**
   *  The message prefix.
   */
  @MessagePrefix
  public static final String m_MessagePrefix = "SFX";
  
  …

For the message id 1, this will generate the message key SFX_000001.

@Translation

This annotation does make sense only in conjunction with the annotations @Message and @Text; it provides the concrete message text in its various translations.

The annotation has the following attributes:

String language

This is the ISO 639-1 two-letter-code for the language of the text; same as for the default language this could be a full fledged locale String as well: think about the following case:

  …
  translations =
  {
      @Translation( language = "de", text = "Farbe" ),
      @Translation( language = "en", text = "Colour" ),
      @Translation( language = "en_US", text = "Color" )
  }
  …

Similar samples where the spelling differs from country to country even inside the same language do exist for several languages.

String text

This is the concrete text – or more correct, that is the format argument for a call to Formatter.format(). This means that it may contain the "%…" placeholders that are defined by Formatter.

If the text will contain more than one placeholder they should be numbered (like "%1$s") because different translation may require different sequences for the arguments that should replace the placeholders; for details, refer to the documentation of Formatter.

@Message

This annotation, that will be applied to an int or String constant, defines the text for a message; the description attribute should describe the message context to allow translators to add further translations; the attribute translations contains the concrete texts as shown in the description for the @Translation, above. The whole thing may look like this:

  …
  @Message
  (
      description = "This message indicates that the socket could not be opened to listen on the given port",
      translations =
      {
          @Translation( language = "en", text = "Cannot open socket on port '%d'" ),
          @Translation( language = "de", text = "Socket kann auf Port '%d' nicht geöffnet werden" )
      }
  )
  public static final int MSG_CannotOpenSocket = 1704;
  …

or

  …
  @Message
  (
      description = "This message indicates that the host with the given name does not respond in time",
      translations =
      {
          @Translation( language = "en", text = "Host '%1$s' does not respond within %2$d milliseconds" ),
          @Translation( language = "de", text = "Der Host '%1$s' hat nicht innerhalb von %2$d ms geantwortet" )
      }
  )
  public static final String MSG_NoResponseFromHost = "NoResponseFromHost";
  …

The key for the resource bundle will be generated from the contents of the constant plus the message prefix – this is different from the behaviour of the @Text annotation.

@Text

Different from the @Message annotation, this annotation can be applied to any kind of field, not only to constants. It has the following attributes:

String description

As for @Message, this should give translators some hints on how to translate the text into the target language.

String id

This optional attribute is the resource bundle key for the text; if missing, that key will be derived from the name of the annotated field.

boolean addClass

If this flag is true, the resource bundle key will be prepended by the fully qualified name of the class that contains the annotated field.

@Translation [] translations

These are the translations for the text, as already described above.

The simplest form to use this annotation looks like this:

  …
  @Text
  (
      description = "The caption for the input field that takes the title of a book",
      translations =
      {
          @Translation( language = "en", text = "Book Title" ),
          @Translation( language = "de", text = "Buchtitel" )
      }
  )
  private static final String CAPTION_BookTitle = I18nUtil.composeTextKey( BookEntryForm.class, TextUse.CAPTION, "BookTitle" );
  …

For the generation of the resource bundle properties files, the content of the field CAPTION_BookTitle is irrelevant, the key will be built from the fully qualified name of the class that contains the field and its name; but for the retrieval of the text, the contents of the field needs to match the generated key.

The prefix CAPTION is defined in TextUse and will be derived from the name of the field in this case. Alternatively, this form can be used that defines both id and use explicitly to get the same key:

  …
  @Text
  (
      description = "The caption for the input field that takes the title of a book",
      id = "BookTitle",
      use = TextUse.CAPTION,
      translations =
      {
          @Translation( language = "en", text = "Book Title" ),
          @Translation( language = "de", text = "Buchtitel" )
      }
  )
  private static final String m_BookTitleCaption = I18nUtil.composeTextKey( BookEntryForm.class, TextUse.CAPTION, "BookTitle" );
  …

Sometimes, enum values should have a human readable representation that needs to be available in different translations. For an enum type named Color this would look like this:

  …
  public enum Color
  {
      @Text
      (
          description = "The colour 'red'",
          translations =
          {
              @Translation( language = "en", text = "red" ),
              @Translation( language = "de", text = "rot" )
          }
      )
      RED,
  
      @Text
      (
          description = "The colour 'yellow'",
          translations =
          {
              @Translation( language = "en", text = "yellow" ),
              @Translation( language = "de", text = "gelb" )
          }
      )
      YELLOW,
  
      …
  
      @Override
      public final toString()
      {
          var bundle = ResourceBundle.getBundle( BASE_BUNDLE_NAME );
          var key = I18nUtil.composeTextKey( this );
          var retValue = I18nUtil.retrieveText( bundle, key );
  
          //---* Done *-----------------------------------------------------------
          return retValue;
      }   //  toString()
  }
  //  enum Color
  …

The argument for the call to ResourceBundle.getString() can be calculated as

Color.class.getName() + ".STRING_" + getName();

This can be used for the implementation of Color.toString() as shown in the sample.

Finally, the annotation can be applied to an arbitrary method, preferred to a getter. This can be used to provide usage texts for the definition of options and arguments, among other possibilities. The sample below assumes that the method getOwner() belongs to the interface com.sample.Example:

  …
  @Text
  (
      description = "The name of the property 'owner'",
      translations =
      {
          @Translation( language = "en", text = "Proprietor/Proprietress" ),
          @Translation( language = "de", text = "Eigentümer/Eigentümerin" )
      }
  )
  @Text
  (
      description = "The caption for the property 'owner'",
      use = TextUse.CAPTION,
      translations =
      {
          @Translation( language = "en", text = "Proprietor (Lastname, Firstname): " ),
          @Translation( language = "de", text = "Eigentümer (Hausname, Vorname): " )
      }
  )
  @Text
  (
      description = "The tooltip for the property 'owner'",
      use = TextUse.TOOLTIP,
      translations =
      {
          @Translation( language = "en", text = "The name of the proprietor" ),
          @Translation( language = "de", text = "Der Name des Eigentümers" )
      }
  )
  @Text
  (
      description = "The usage text for the property 'owner'",
      use = TextUse.USAGE,
      translations =
      {
          @Translation( language = "en", text = "The name of the proprietor" ),
          @Translation( language = "de", text = "Der Name des Eigentümers" )
      }
  )
  @Option( name = "-o", aliases = {"--owner", "--proprietor"}, metavar = "NAME", usage = "The name of the proprietor", usageKey = "com.sample.Example.USAGE_Owner" )
  public String getOwner();
  …

The generated resource bundle keys for the texts are:

• com.sample.Example.NAME_Owner
• com.sample.Example.CAPTION_Owner
• com.sample.Example.TOOLTIP_Owner
• com.sample.Example.USAGE_Owner

This works because com.sample.Example.getOwner() is a getter method and the name of the property ("owner") will be taken as the id.

For method that are not getters, setters or "add" methods, id and use have to be set explicitly, otherwise an exception is thrown by the annotation processor.

It is a bit clumsy that the generated key has to be guessed for the value of the usageKey attribute of the @Option and @Argument annotations (defined in config module). This is because the annotation processor cannot modify existing source code, and because annotation attributes do allow only compile time constants as values. That's also the reason why the resource bundle keys have to be generated from the annotation attributes, instead of taking the value of the field.

Additional Texts

Sometimes it is not feasible or just not wanted to define the messages and texts as annotations to fields or methods. This is quite often the case for longer texts, like help output, or for the texts used to build a (G)UI.

To address this, texts can be defined in file named "AdditionalTexts.xml". This file can be located in the root of the source tree, but its location can be also configured through the annotation processor option "org.tquadrat.foundation.i18n.ap.textLocation", or it can be provided through the annotation @UseAdditionalTexts.

That file has to comply the DTD below, defined in AdditionalText.dtd.

AdditionalText.dtd

<?xml version="1.0"
      encoding="UTF-8"?>

<!--
  - ============================================================================
  -  Copyright © 2002-2021 by Thomas Thrien.
  -  All Rights Reserved.
  - ============================================================================
  -  Licensed to the public under the agreements of the GNU Lesser General Public
  -  License, version 3.0 (the "License"). You may obtain a copy of the License at
  -
  -       http://www.gnu.org/licenses/lgpl.html
  -
  -  Unless required by applicable law or agreed to in writing, software
  -  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  -  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  -  License for the specific language governing permissions and limitations
  -  under the License.
  -->
<!-- $Id: AdditionalText.dtd 887 2021-03-28 19:25:19Z tquadrat $ -->

<!ELEMENT description ( #PCDATA )>

<!ELEMENT text (description, translation+)>
<!ATTLIST text
    key ID #REQUIRED>
<!ELEMENT texts (text*)>

<!ELEMENT translation ( #PCDATA )>
<!ATTLIST translation
    language CDATA #REQUIRED>

<!-- End of File -->

Class	Description
BaseBundleName	This annotation is used to mark a String constant that holds the base bundle name for the resource bundle for the messages and texts.
I18nUtil	Utilities that are related to the i18n feature.
Message	Use this annotation to define the text for a message that has to be translated. Texts for UI elements or alike will be defined with the annotation Text.
MessagePrefix	The annotation is used to mark a String constant that holds the message prefix for the generated messages.
NoText	Marker for omitted texts.
NoTexts	The container annotation for repeated @NoText annotations.
Text	Use this annotation to define a text – usually for a UI element or alike – that has to be translated.
Texts	The container annotation for repeated @Text annotations.
TextUse	The uses for a text.
Translation	Use this annotation to define a text for a message or a UI element that has to be translated.
UseAdditionalTexts	This optional annotation provides the location for the file "AdditionalTexts.xml" if that is not stored at the default locations