localization

Every Gaderian module may have its own set of messages. Messages are stored alongside the module deployment descriptor, as META-INF/org/ops4j/gaderian/module.properties (within the module's JAR).

Note
In actuality, the name of the properties file is created by stripping off the extension (".xml") from the descriptor name and appending the localization code and ".properties". This is relevant only if you load your module deployment descriptors from a non-standard location, possibly via the <sub-module> element.

Services can gain access to localized messages, as an instance of Messages , which includes methods for accessing messages and formatting messages with arguments.

In a module descriptor, within the <contribution> and <invoke-factory> elements, you can reference a localized message in an attribute or element content simply by prefixing the message key with '%'. Examples:

 
<contribution configuration-id=...>
  <some-item> <message="%message.key">
    %other.message.key
  </some-item>
</contribution>

The two keys (message.key and other.message.key ) are searched for in the contributing module's messages.

Warning
Support for this '%' syntax will likely be removed soon. This is because the locale is now changeable; what locale to use when converting configuration data becomes dangerously ambiguous.

Gaderian gracefully recovers from undefined messages. If a message is not in the properties file, then Gaderian provides a substitute value by converting the key to upper-case and adding brackets, i.e. [MESSAGE.KEY]. This allows your application to continue running, but clearly identifies missing messages.

By adding additional files, message localization can be accomplished. For example, adding a second file, META-INF/org/ops4j/gaderian/module_fr.properties would provide French language localizations. Any common keys between the two files defer to the more specific file.

The gaderian.BuilderFactory can inject an Messages object that allows access to the module's messages.

Setting the locale

When a Registry is created by the RegistryBuilder, a locale is specified. This is the default locale for the Registry and, by extension, for all Modules in the registry.

Threads will always use this locale by default, but the locale for an individual thread may be changed using the gaderian.ThreadLocale service. The Messages injected into your services automatically adjusts for the thread's current locale.

You should not store, in your services, any localized values, since different threads may want different localizations. Instead, you should always obtain values from the Messages.