Module org.tquadrat.foundation.i18n

Package org.tquadrat.foundation.i18n

Annotation Interface Text

@Retention(SOURCE)
@Target({FIELD,METHOD})
@Repeatable(Texts.class)
@ClassVersion(sourceVersion="$Id: Text.java 1062 2023-09-25 23:11:41Z tquadrat $")
@API(status=STABLE,
     since="0.1.0")
public @interface Text

Use this annotation to define a text – usually for a UI element or alike – that has to be translated. Messages will be defined with the annotation Message.

The texts will be stored in a ResourceBundle with the base bundle name that is identified through the annotation @BaseBundleName. The documentation for the method getBundle() describes the detection strategy. The build process takes care of the generation of the resource bundle properties file.

Use this annotation as follows:

  …
  @Text
  (
      description = "A text",
      translations =
      {
          @Translation( language = "en", text = "English text" ),
          @Translation( language = "de", text = "Text in Deutsch" )
      }
  )
  private static final String TXT_TextKey = I18nUtil.composeTextKey( SampleClass.class, TextUse.TXT, "TextKey" );
  …

For the generation, the content of the field TXT_TextKey is irrelevant, the key will be built from the name of the field plus the fully qualified name of the class. But for the retrieval of the text, the contents of the field needs to match that generated key.

The prefix TXT is defined in TextUse and will be derived from the name; if this is not desired, an alternative form of the annotation can be used:

  …
  @Text
  (
      …
  )
  private static final String m_TextKey = I18nUtil.composeTextKey( SampleClass.class, TextUse.TXT, "TextKey" );
  …

This works because TXT is the default for the text use.

It is also possible to define the id and the text use explicitly:

  …
  @Text
  (
      description = "A text",
      id = "TextKey",
      use = TextUse.TXT,
      translations =
      {
          @Translation( language = "en", text = "English text" ),
          @Translation( language = "de", text = "Text in Deutsch" )
      }
  )
  private static final String m_Text = I18nUtil.composeTextKey( SampleClass.class, TextUse.TXT, "TextKey" );
  …

This format is required when the annotation is applied to a method, in this case to a getter:

  …
  @Text
  (
      description = "The name of the property",
      translations =
      {
          @Translation( language = "en", text = "Property" ),
          @Translation( language = "de", text = "Eigenschaft" )
      }
  )
  @Text
  (
      description = "The caption for the property",
      use = TextUse.CAPTION,
      translations =
      {
          @Translation( language = "en", text = "Property: " ),
          @Translation( language = "de", text = "Eigenschaft: " )
      }
  )
  @Text
  (
      description = "The tooltip for the property",
      use = TextUse.TOOLTIP,
      translations =
      {
          @Translation( language = "en", text = "The property" ),
          @Translation( language = "de", text = "Die Eigenschaft" )
      }
  )
  public String getProperty();
  …

This sample would generate texts with the keys below, given that the method belongs to the interface com.sample.Example:

• com.sample.Example.NAME_Property
• com.sample.Example.CAPTION_Property
• com.sample.Example.TOOLTIP_Property

If the method is not a getter, a setter or an "add" method, both id and use are always mandatory.

For enums, this form is applicable:

  …
  public enum WhatEver
  {
      @Text
      (
          description = "The name for an enum value",
          translations =
          {
              @Translation( language = "en", text = "Enumeration Value" ),
              @Translation( language = "de", text = "Aufzählungswert" )
          }
      )
      ENUM_VALUE;

      …
  }
  //  enum WhatEver

The argument for ResourceBundle.getString() in this case can be composed through a call to I18nUtil.composeTextKey(); that can be used for the implementation of WhatEver.toString() like this:

  …
  public final toString()
  {
      String key = composeTextKey( this );
      String retValue = getBundle().getString( key );

      //---* Done *-----------------------------------------------------------
      return retValue;
  }  //  toString()
  …

Different from messages, it is somehow expected that the returned values may contain escape sequences that can be converted by a call to String.translateEscapes().

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: Text.java 1062 2023-09-25 23:11:41Z tquadrat $

Since:

0.1.0

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	description	Returns the description for the text.
Translation[]	translations	Returns the list of valid translations for the text.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	id	Returns the text id for the text.
TextUse	use	The use of the text; the default is TextUse.TEXTUSE_DEFAULT.

Element Details

description

String description

Returns the description for the text.

Returns:

The description.

use

TextUse use

The use of the text; the default is TextUse.TEXTUSE_DEFAULT.

This will be replaced with TextUse.NAME if the annotated element is method for a property (a getter, setter or an "add" method), with TextUse.STRING if an enum is annotated, and with TextUse.TXT for any other case.

Returns:

The text use.

Default:

TEXTUSE_DEFAULT

id

String id

Returns the text id for the text. If empty, the name of the annotated field is used when the annotation is applied to field; otherwise the annotation processor will throw an error.

Returns:

The id, if set; otherwise the empty String.

Default:

""

translations

Translation[] translations

Returns the list of valid translations for the text.

Returns:

The translations.