5.272 i18n Messaging

Plugins, translators, and custom components all have access to i18n messages. Utilizing messages requires the two following steps:

Including a file (or multiple files) that ends in "messages.properties" in the plugin JAR file.
Using the message method on a plugin type, translator, or custom component.

Including messages in plugin JAR file

Messages are defined using property files. These may be named anything as long as they end with "messages.properties" and must be placed at the root or top level of the plugin JAR file. If they are present, they will be loaded automatically. Multiple property files may be used within a single plugin JAR file.

Each property file consists of an arbitrary amount of lines that define a message property (also called a code) with letters, numbers, and periods, associated with a human-readable message that can span multiple lines, have quotes, or contain arguments. These are demonstrated in the following example.

first.message.code=This is the first message
second.message=This message can span multiple lines, \\
  and will not show the linebreaks when retrieved
message.with.arguments=This message has arguments: first - {0}, second - {1}, third - {2}, etc.
message.with.quotes=This message uses single quotes around ''this phrase''.

It is recommended to namespace the messages by using the property definitions and multiple property files if necessary. For example, suppose a plugin JAR existed which actually contained two plugin types: Message1Plugin and Message2Plugin. The first suggestion is to namespace the messages for each plugin by the property definition, such as the following:

message1Plugin.first.message=This is a message for Message1Plugin
message2Plugin.first.message=This is a message for Message2Plugin

These messages could be stored in a file named "messages.properties" in the root of the plugin JAR file. If there are many messages contained for each plugin type, it may be necessary to split each plugin type's messages into a separate file, such as "message1-messages.properties" and "message2-messages.properties". Note that it is essential that each property file ends with "messages.properties" so that it is registered correctly.

It is important that no two message codes are identical within a single plugin JAR file, even if they are defined in separate property files. If this is done, a conflict will exist with the messages and behavior is undefined.

Using the message method

Each plugin, translator, and custom component is injected with a method named message. This method takes a Map as its parameter, which can contain one or several of the following properties:

Parameter	Type	Description
code	String	The message property definition (everything before the equals sign in the property file for a single message), for example, first.message.code.
args	List<Object>	A list of arguments to insert into the message.
default	String	A default message to be used when the message code cannot be resolved.
error	org.springframework.context.MessageSourceResolvable	An object that represents a hierarchy of message codes. This is typically used to display errors.

The most utilized parameters are code and args, as these combined provide great flexibility in generating messages. If a message cannot be resolved, or in other words the message definition does not exist, the code will simply be returned as the resolved message. Below are several examples of messages resolved using the property files given above. While these are contained in the polling method, the message may be used anywhere within a plugin type.

package example
import com.adaptc.mws.plugins.AbstractPlugin

class MessagingPlugin extends AbstractPlugin {
	def poll() {
		assert message(code:"first.message.code")=="This is the first message"
		assert message(code:"message.with.arguments", args:[
				"1st", 2, true
			])=="This message has arguments: first - 1st, second - 2, third - true, etc."
		assert message(code:"message.with.quotes")=="This message uses single quotes around 'this phrase'."
		assert message(code:"invalid.message.code")=="invalid.message.code"
	}
}