Package com.google.gwt.i18n.client

Interface Messages

All Superinterfaces:
Localizable, Localizable, LocalizableResource
All Known Subinterfaces:
CellTree.CellTreeMessages
public interface Messages extends LocalizableResource
A tag interface that facilitates locale-sensitive, compile-time binding of messages supplied from various sources.Using GWT.create(class) to "instantiate" an interface that extends Messages returns an instance of an automatically generated subclass that is implemented using message templates selected based on locale. Message templates are based on a subset of the format used by MessageFormat. Note in particular that single quotes are used to quote other characters, and should be doubled for a literal single quote.

Locale is specified at run time using a meta tag or query string as described for Localizable.

Extending Messages

To use Messages, begin by defining an interface that extends it. Each interface method is referred to as a message accessor, and its corresponding message template is loaded based on the key for that method. The default key is simply the unqualified name of the method, but can be specified directly with an @Key annotation or a different generation method using @GenerateKeys. Additionally, if plural forms are used on a given method the plural form is added as a suffix to the key, such as widgets[one] for the singular version of the widgets message. The resulting key is used to find translated versions of the message from any supported input file, such as Java properties files. For example, 
public interface GameStatusMessages extends Messages {
  /**
   * @param username the name of a player
   * @param numTurns the number of turns remaining
   * @return a message specifying the remaining turns for a player
   */
  String turnsLeft(String username, int numTurns);

  /**
   * @param numPoints the number of points
   * @return a message describing the current score for the current player
   */
  String currentScore(int numPoints);
}
expects to find properties named turnsLeft and currentScore in an associated properties file, formatted as message templates taking two arguments and one argument, respectively. For example, the following properties would correctly bind to the GameStatusMessages interface: 
turnsLeft = Turns left for player ''{0}'': {1}
currentScore = Current score: {0}

The following example demonstrates how to use constant accessors defined in the interface above: 

public void beginNewGameRound(String username) {
  GameStatusMessages messages = (GameStatusMessages) GWT.create(GameStatusMessages.class);

  // Tell the new player how many turns he or she has left.
  int turnsLeft = computeTurnsLeftForPlayer(username);
  showMessage(messages.turnsLeft(username, turnsLeft));

  // Tell the current player his or her score.
  int currentScore = computeScore(username);
  setCurrentPlayer(username);
  showMessage(messages.currentScore(currentScore));
}

The following example shows how to use annotations to store the default strings in the source file itself, rather than needing a properties file (you still need properties files for the translated strings): 

public interface GameStatusMessagesAnnot extends Messages {
  /**
   * @param username the name of a player
   * @param numTurns the number of turns remaining
   * @return a message specifying the remaining turns for a player
   */
  @DefaultMessage("Turns left for player ''{0}'': {1}")
  String turnsLeft(String username, int numTurns);

  /**
   * @param numPoints the number of points
   * @return a message describing the current score for the current player
   */
  @DefaultMessage("Current score: {0}")
  String currentScore(int numPoints);
}

In this example, calling msg.turnsLeft("John", 13) would return the string "Turns left for player 'John': 13".

Defining Message Accessors

Message accessors must be of the form 
String methodName(optional-params)
and parameters may be of any type. Arguments are converted into strings at runtime using Java string concatenation syntax (the '+' operator), which uniformly handles primitives, null, and invoking toString() to format objects.

Compile-time checks are performed to ensure that the number of placeholders in a message template (e.g. {0}) matches the number of parameters supplied.

Integral arguments may be used to select the proper plural form to use for different locales. To do this, mark the particular argument with @PluralCount (a plural rule may be specified with @PluralCount if necessary, but you will almost never need to do this). The actual plural forms for the default locale can be supplied in a @PluralText annotation on the method, such as @PluralText({"one", "You have one widget"}), or they can be supplied in the properties file as methodkey[one]=You have one widget. Note that non-default plural forms are not inherited between locales, because the different locales may have different plural rules (especially default and anything else and those which use different scripts such as sr_Cyrl and sr_Latn [one of which would likely be the default], but also subtle cases like pt and pt_BR).

Additionally, individual arguments can be marked as optional (ie, GWT will not give an error if a particular translation does not reference the argument) with the @Optional annotation, and an example may be supplied to the translator with the @Example(String) annotation.

Complete Annotations Example

In addition to the default properties file, default text and additional metadata may be stored in the source file itself using annotations. A complete example of using annotations in this way is: 
 @Generate(format = "com.google.gwt.i18n.rebind.format.PropertiesFormat")
 @DefaultLocale("en_US")
 public interface MyMessages extends Messages {
   @Key("1234")
   @DefaultMessage("This is a plain string.")
   String oneTwoThreeFour();
   
   @DefaultMessage("You have {0} widgets")
   @PluralText({"one", "You have one widget")
   String widgetCount(@PluralCount int count);
   
   @DefaultMessage("No reference to the argument")
   String optionalArg(@Optional String ignored);
   
   @DefaultMessage("Your cart total is {0,number,currency}")
   @Description("The total value of the items in the shopping cart in local currency")
   String totalAmount(@Example("$5.00") double amount);
   
   @Meaning("the color")
   @DefaultMessage("orange")
   String orangeColor();
   
   @Meaning("the fruit")
   @DefaultMessage("orange")
   String orangeFruit();
 }

Binding to Properties Files

Interfaces extending Messages are bound to resource files using the same algorithm as interfaces extending Constants. See the documentation for Constants for a description of the algorithm.

Required Module

Modules that use this interface should inherit com.google.gwt.i18n.I18N. 
<module>
  <!-- other inherited modules, such as com.google.gwt.user.User -->
  <inherits name="com.google.gwt.i18n.I18N"/>
  <!-- additional module settings -->
</module>

Note

You should not directly implement this interface or interfaces derived from it since an implementation is generated automatically when message interfaces are created using GWT.create(Class).