The ForgeRock I18N Framework for Java provides an easy to use type safe
API for obtaining localizable messages.
Getting started
In order to get started using this framework you should first define some
localized messages in property files and locate these in your resource
directory. For example, consider the following simple properties files:
src/main/resources/com/example/myapp/core.properties
MESSAGE_WITH_NO_ARGS=Message with no args
MESSAGE_WITH_STRING=Arg1=%s
MESSAGE_WITH_STRING_AND_NUMBER=Arg1=%s Arg2=%d
src/main/resources/com/example/myapp/core_fr.properties
MESSAGE_WITH_NO_ARGS=French message with no args
MESSAGE_WITH_STRING=French Arg1=%s
MESSAGE_WITH_STRING_AND_NUMBER=French Arg1=%s Arg2=%d
Once you have your property files defined you can use the
i18n-maven-plugin to generate the messages. To do this, add the
following lines to your pom.xml:
<repositories>
<repository>
<id>forgerock-staging-repository</id>
<name>ForgeRock Release Repository</name>
<url>http://maven.forgerock.org/repo/releases</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<build>
<plugins>
<plugin>
<groupId>org.forgerock.commons</groupId>
<artifactId>i18n-maven-plugin</artifactId>
<version>1.4.2</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>generate-messages</goal>
</goals>
<configuration>
<messageFiles>
<messageFile>com/example/myapp/core.properties</messageFile>
</messageFiles>
</configuration>
</execution>
</executions>
</plugin>
</build>
This will generate a Java file in
target/generated-sources/messages/com/example/myapp/CoreMessages.java
containing {@link org.forgerock.i18n.LocalizableMessageDescriptor}s for each
message contained in the property file. For example:
public final class CoreMessages
{
...
/**
* Message with no args
*/
public static final LocalizableMessageDescriptor.Arg0 MESSAGE_WITH_NO_ARGS =
new LocalizableMessageDescriptor.Arg0(CoreMessages.class,RESOURCE,"MESSAGE_WITH_NO_ARGS",-1);
/**
* Arg1=%s
*/
public static final LocalizableMessageDescriptor.Arg1<CharSequence> MESSAGE_WITH_STRING =
new LocalizableMessageDescriptor.Arg1<CharSequence>(CoreMessages.class,RESOURCE,"MESSAGE_WITH_STRING",-1);
/**
* Arg1=%s Arg2=%d
*/
public static final LocalizableMessageDescriptor.Arg2<CharSequence,Number> MESSAGE_WITH_STRING_AND_NUMBER =
new LocalizableMessageDescriptor.Arg2<CharSequence,Number>(CoreMessages.class,RESOURCE,"MESSAGE_WITH_STRING_AND_NUMBER",-1);
}
To use the generated messages you'll need the following dependency:
<groupId>org.forgerock.commons</groupId>
<artifactId>i18n-core</artifactId>
<version>1.4.2</version>
<scope>compile</scope>
Messages can then be instantiated in a type safe manner which is enforced at
compile time (unlike CAL10N) as well as avoiding runtime errors due to
missing properties (CAL10N has this too):
LocalizableMessage m = MESSAGE_WITH_STRING_AND_NUMBER.get("a string", 123);
String s1 = m.toString(); // Default locale.
String s2 = m.toString(Locale.FRENCH);
// Using SLF4J support: using logger "com.example.mayapp.core" and default locale.
LocalizedLogger logger = LocalizedLoggerFactory.getInstance(CoreMessages.resourceName());
logger.error(MESSAGE_WITH_STRING_AND_NUMBER, "a string", 123);
Note that it is also possible to associated an ordinal with each message by
appending a number to the end of the property name. For example, the following
message will have the ordinal 389:
src/main/resources/com/example/myapp/core.properties
MESSAGE_WITH_ORDINAL_389=Message with ordinal
The ordinal can be retrieved by calling the method
{@link org.forgerock.i18n.LocalizableMessage#ordinal()}. This allows each
message to be uniquely identified by its ordinal and its resource name
(e.g. "com.example.mayapp.core"), the latter being obtained by calling the
method {@link org.forgerock.i18n.LocalizableMessage#resourceName()} which is
also available in each generated message file. The ability to uniquely identify
log messages is useful when diagnosing log messages which have been output in a
locale that you don't understand.