I18N

From alfrescowiki

Jump to: navigation, search

Warning: Page Needs Work
This page has been identified as one that needs specific attention to maintain, expand, correct, or improve. The specific needs should be listed on the discussion page. Please consider making the requested changes.

Back to Developer Guide

Setting the current locale

The current locale is set on a per-thread basis. This is performed automatically by the Alfresco web client, but must be done manually otherwise. If no Locale is specified the repository will revert to the default Locale.

Use the following methods found on org.alfresco.i18n.I18NUtil to set and get the current Locale.

    /**
     * Set the locale for the current thread.
     * 
     * @param locale    the locale
     */
    public static void setLocale(Locale locale) { ...

    /**
     * Get the local for the current thread, will revert to the default locale if none 
     * specified for this thread.
     * 
     * @return  the Locale
     */
    public static Locale getLocale() { ...

Resource bundles

All user displayed strings that originate in the repository should be externalised into resource bundles to ensure that the repository is fully localisable.

Examples of strings requiring extraction include:

  • Descriptive display labels used by a client
  • Error messages

Extracted strings should be gathered into resource bundles by functional area. This enables functional areas to remain distinct within the repository.

The base bundle should be named by functional area and have the '.properties' extension. All base bundles should be in US English.

If a message needs to be parameterised the Java MessageFormatter style should be used. (see example)

The ids used in the resource bundles should be scoped by functional area to avoid clashes (this is important since at runtime the contents of the various resource bundles in combined, any names clashes will result in message values being overwritten).

A resource bundle can be placed anywhere in the source tree, but in general repository resource bundles should be placed in the alfresco.messages package found in the config directory.

Example resource bundle contents:

   # User displayed string for the rule service functional area

   ruleservice.error=There has been an error executing rule {0}.
   ruleservice.confimation_all=All rules have been executed.

Registering a resource bundle

Before a resource bundle can be used by the repository it must be registered.

This can be perfomed by manually calling the following method found on org.alfresco.i18n.I18NUtil

   /**
    * Register a resource bundle.
    * <p>
    * This should be the bundle base name eg, alfresco.messages.errors
    * <p>
    * Once registered the messges will be available via getMessage
    * 
    * @param bundleBaseName    the bundle base name
    */
   public static void registerResourceBundle(String bundleBaseName) { ...

However the recommended approach is to introduce the resource using Spring config.

The following is an example of a snippet of Spring config that achieves this.

   <bean id="actionResourceBundles" class="org.alfresco.i18n.ResourceBundleBootstrapComponent">
      <property name="resourceBundles">
         <list>
    	    <value>alfresco.messages.action-config</value>
    	 </list>
      </property>
   </bean>

Note that the values passed to the ResourceBundleBootstrapComponent are the base names for the resource bundles. See the Java documentation for java.util.ResourceBundle for details of what the base name of a resource bundle is.

Retrieving localised strings

Once registered, the contents of a resource bundle can be retrieved using follwing methods found on org.alfresco.i18n.I18NUtil.

    /**
     * Get message from registered resource bundle.
     * 
     * @param messageKey    message key
     * @return              localised message string, null if not found
     */
    public static String getMessage(String messageKey) { ...
    
    /**
     * Get a localised message string
     * 
     * @param messageKey        the message key
     * @param locale            override the current locale
     * @return                  the localised message string, null if not found
     */
    public static String getMessage(String messageKey, Locale locale) { ...
    
    /**
     * Get a localised message string, parameterized using standard MessageFormatter.
     * 
     * @param messageKey    message key
     * @param params        format parameters
     * @return              the localised string, null if not found
     */
    public static String getMessage(String messageKey, Object[] params) { ...
    
    /**
     * Get a localised message string, parameterized using standard MessageFormatter.
     * 
     * @param messageKey        the message key
     * @param params            the localised message string
     * @param locale            override current locale
     * @return                  the localaised string, null if not found
     */
    public static String getMessage(String messageKey, Object[] params, Locale locale) { ...

I18N exception support

All exception messages should be externalised and the localised strings retrieved when raising an exception.

The AlfrescoRuntimeException class is linked to the I18N capabilities of the repository and will automatically retrieve the localised string when passed a message id and, optionally, a set of parameters.

If the message id passed does not resolve to a localised string then the id is used as the exception message.

The following constructors are available on AlfrescoRuntimeException.

   public AlfrescoRuntimeException(String msgId) { ... 
   public AlfrescoRuntimeException(String msgId, Object[] msgParams) { ...   
   public AlfrescoRuntimeException(String msgId, Throwable cause) { ...    
   public AlfrescoRuntimeException(String msgId, Object[] msgParams, Throwable cause) { ...

Localising resource bundles

In order to localise a resource bundle the original must first be renamed according to the Locale of the localisation.

For example if the base resource bundle is called rule-service.properties, then the French localisation of that bundle should be called rule-service_fr_FR.properties. For more information about this see the Java documentation on java.util.ResourceBundle.

Once the strings in the localised resource bundle have been translated it should be placed in the same location in the source tree as the base resource bundle.

Now the localised string will be available when the locale is switched.

Personal tools
© 2014 Alfresco Software, Inc. All Rights Reserved. Legal | Privacy | Accessibility