Customizing the UI Language using i18n

The best practice for changing the language used in the OnePart UI is to add the language file to the product’s configuration (rather than directly translating the default English language file, onePart.properties). This section also covers how to Develop with I18N.

This task shows you how to:

Basis workflow

The basic workflow is:

Before you begin:

Manage the OnePart UI languages

The default OnePart UI language is determined by:

  • the user’s preferences if available or set to ‘Automatic’

  • the user’s browser settings if available

  • lastly,OnePart uses the default language set in the product configuration

To change the default language

You can change the OnePart UI’s default language in the product configuration. For example, to change the default language to French, set the value to fr as shown below.

  1. In webapps\360-mashup-ui\WEB-INF\360-search-ui.xml, set the value to the ISO language of your choice, for example: Replace <property name="default” value="en"/> by <property name="default" value="fr"/>
  2. Go to the Home page in the Administration Console and restart the search server in the list of Processes; see below.



Add a new language to the OnePart UI

By default, OnePart UI displays in English, French, German, Japanese, Chinese and Korean. Users can choose their preferred display language in the UI’s user preferences. Get the ISO 639-1 code for the language you want to add. As an example we will add the Creole which ISO code is ht. Declare a new language as follows:

  1. Edit ONEPART_INSTALLDIR\webapps\360-mashup-ui\WEB-INF\360-search-ui.xml
    1. Add line <value>ht</value> after <value>ja</value>
    2. Save.
  2. Edit ONEPART_INSTALLDIR\webapps\360-mashup-ui\WEB-INF\i18n\onepart.properties
    1. Add line preferences_box_general_item_locale_ht=Creole after preferences_box_general_item_locale_ja=日本語
    2. Save.
  3. Go to ONEPART_INSTALLDIR\datadir\webapps\360-mashup-ui\WEB-INF\i18nx
    1. Copy onepart.properties to onepart_ht.properties.
    2. Translate all the keys for the language you require, in this example, Creole. See also, To configure the UI labels
    3. Save.
  4. Restart search server
    User can now choose the Creole language in their user preferences.

OnePart properties files

OnePart provides the resource files for English, French, German, Japanese, Chinese and Korean in <PRODUCT>\WEB-INF\i18n:

  • onePart_xx.properties (OnePart UI labels)
  • messages_xx.properties (standard error messages)

Property name convention

Adding internationalization to meta or facet names can be performed following a simple convention for property names:

  • all metas are prefixed by meta_
  • and facets by facet_.

For example:

  • meta_publicurl=Public URL
  • facet_Top/person/author=Authors

Global label change

The global properties file defined in \WEB-INF\i18n\messages*.properties override the widget ones, defined in \WEB-INF\jsp\widgets\*\messages*.properties.

Therefore, if you edit the global properties file, all metas named, for example, publicurl will be renamed Public URL in the OnePart UI. This is practical for attributes values (such as material name, etc.) that are displayed in their original form, English most of the time.

Important: The override mechanism is case-sensitive. Be careful to use the correct case in your properties files.
Specific widget label

If you want this change to be applied on a specific widget, edit the messages*.properties file located in the widget’s folder.

To create new *.properties files

Create the *_<ISO NAME >.properties files for the new language.

  1. In <PRODUCT>\WEB-INF\i18N copy the messages.properties and onePart.properties files to create the new language files named *_<ISO NAME >.properties.

    For example, for Japanese, create onePart_ja.properties and messages_ja.properties

  2. Translate the language specific files. See To configure the UI labels.
  3. Restart the search server in the Administration Console.
To configure the UI labels

Configure the UI labels as follows.

  1. Edit the properties file:

    <ONEPART_INSTALLDIR>\datadir\webapps\360-mashup-ui\WEB-INF\i18n\onePart_<ISO NAME>.properties for the language you require.

    Note: We recommend that you maintain all the i18n labels used in the OnePart UI in this centralized file.

  2. Edit the existing meta or facet label value you want to display in the UI.
  3. For a new facet, add it under # Facets in the format:

    facet_<facet_Root>=<UI label> For example, facet_Top/classproperties/file_folder= File folder

    See Add a new meta to the data model

  4. For a new meta, add it under # Metas in the format: meta_<new_meta>=<UI label>

    For example, meta_project= Project

  5. Save the file.
  6. Restart the search server in the Administration Console.
Develop with I18N

The details to develop with i18n are below.

  1. Add the <SupportI18N> tag in the widget.xml, for example:

    Note: This <SupportI18N> xml tag allows all messages*.properties files located in the widget folder to be loaded by the I18NLoader automatically. 

    <Widget name="Widget name">
...
<SupportI18N supported="true" />
...
</Widget>
  2. Convert JSP pages to use the <i18n:message> tag from the i18n tag library 
    <%@ taglib prefix="i18n" uri="http://www.exalead.com/jspapi/i18n" %>
  3. The <wh:i18n> tag is a subset of the Spring <spring:message> tag (see http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/servlet/tags/MessageTag.html)

    Note: If the key application.name is undefined in all the properties files, the attribute text="" is used as backup. 

    <i18n:message code="application.name" text="hola mundo" />
  4. By convention, all metas are prefixed by meta_ and facets by facet_. i18n must be cleaned that's why it is safer to use: 
    <search:getMetaLabel metaName=${metaName}/>
<search:getFacetLabel  facetPath=”${category.path}”>
  5. I18N can be used server-side like in a custom controller. To achieve this, you need the ServletContext and the HttpServletRequest, for example: 
    import java.util.Locale;
import org.springframework.context.MessageSource;
import org.springframework.web.context.support.WebApplicationContextUtils;
MessageSource messageSource = (MessageSource)
WebApplicationContextUtils.getWebApplicationContext(this.pageContext.getServl
etContext()).getBean("messageSource");
Locale locale = RequestContextUtils.getLocale((HttpServletRequest)
this.pageContext.getRequest());
String str = I18NLoader.getMessage(messageSource, "application.name", "hola mundo",
locale);
System.out.println(str);