Understanding Languages in Liferay Portal #

Liferay is designed to handle as many languages as you want to support. This is done by pulling out all language specific text and storing them in language.properties files. This way, when a page loads, Liferay will detect the language, pull up the corresponding language file and display the text in the correct language.

With this you can:

• Easily support as many (or as few) languages as desire
• Have a central location for multiple languages
• Change the way a certain word is translated. If you wanted, you could effectively rename the "message boards" portlet to now be called "forums".

Customizations in portal.properties #

Liferay has many properties that can be easily configured to customize the portal. These can be found in the portal.properties file located portal/portal-impl/classes/portal.properties. To modify these values, create an ext version of this file which only contains the values you want to override. This ext version should be placed here: /ext/ext-impl/classes/portal-ext.properties

Setting a default Language and default Country #

You'll find the below setting in your system.properties file.

 #
 # Set the default language.
 #
 user.country=TR
 user.language=tr

Setting up a unique URL for different languages #

Liferay allows you to provide a unique URL for a specific language via our I18nServlet.

Examples are:

The mappings for this is done in web.xml:

<servlet-mapping> 
<servlet-name>I18nServlet</servlet-name> 
<url-pattern>/de/*</url-pattern> 
</servlet-mapping> 
<servlet-mapping> 
<servlet-name>I18nServlet</servlet-name> 
<url-pattern>/zh_CN/*</url-pattern> 
</servlet-mapping> 
<servlet-mapping> 
<servlet-name>I18nServlet</servlet-name> 
<url-pattern>/zh_TW/*</url-pattern> 
</servlet-mapping> 

This functionality would then allow you to point specific domains to a specific language of a site. (i.e. www.liferay.cn -> Chinese version of www.liferay.com)

Removing unwanted language #

By default, Liferay supports all the follow languages (excerpt from portal.properties of Liferay 4.3.3):

    locales=ar_SA,ca_AD,ca_ES,zh_CN,zh_TW,cs_CZ,nl_NL,en_US,fi_FI,fr_FR,de_DE,el_GR,hu_HU,it_IT,ja_JP,ko_KR,fa_IR,pt_BR,ru_RU,es_ES,sv_SE,tr_TR,vi_VN

If we only want to support English, German and Spanish, we simply remove the unwanted locales so that our locales value looks like this:

   locales=en_US,de_DE,es_ES   

Customizations in language.properties and other language files #

Priority of Language files #

There are many language files and every language file overwrites another language file, what is the priority of these language files?

There are three simple rules:

• -ext versions take precedence over the non -ext versions
• language specific versions take precedence over the non language specific versions
• location specific versions take precedence over the non location specific versions

For English, here is a ranking

1. Language-ext_en_US.properties
2. Language_en_US.properties
3. Language-ext_en.properties
4. Language_en.properties
5. Language-ext.properties
6. Language.properties

Language/display information is defined in /portal/portal-ejb/classes/content/Language.properties, as well as various other Language_.properties files for foreign languages. Language.properties is the primary and "default" language definition file, but definitions in that file may be overriden by language specific definitions. For example, the file Language_en.properties contains the english versions of most of the definitions. The file Language_fr.properties contains the french version, etc.

Language files can further have locale specific definitions. Language_en_US.properties (if it exists), contains english phrase variations further defined for the United States. Other languages can also have locale specific definitions.

Entries in the language files can be re-defined on a deployment by deployment basis by overriding -ext.properties files stored in the /ext/ext-ejb/classes/content/ directory. /ext/ext-ejb/classes/content/Language-ext.properties, for example, overrides and/or extends the definitions found in /portal/portal-ejb/classes/content/Language.properties.

Important Notes #

1. The locale specific definitions takes precedence, followed by language specific, followed by the default. Since most of the entries in Language.properties have language specific entries in Language_xx.properties, those will always take precedence. To override entries in Language_en.properties, for example, you would put your new entries in /ext/ext-ejb/classes/content/Language-ext_en.properties. As of Liferay 4.1.2, few locale specific files exist (there is no locale specific variations of the english file for example). The HIGHEST precedenced file for the United States, for example, is the extension to Language_en_US.properties, which would be /ext/ext-ejb/classes/content/Language-ext_en_US.properties. If you find your changes are not appearing, try putting them in that file.
2. If there is more than one locale for the same language defined in the locales property, the first one in the list will be used when a translation is requested in another locale of the same language but a translated value cannot be found. For example, if there are two locales such us pt_BR and pt_PT (in this order), any key not found in pt_PT will be looked for in pt_BR.

Changing existing language entries #

Example: Changing the text of an existing portlet in Liferay from "Message Boards" to "Forums" #

Liferay currently displays "Message Boards" because of the entry in:

portal\portal-ejb\classes\content\Language_en.properties

javax.portlet.title.19=Message Boards

To change this, modify (or create) your Language-ext_en.properties file and add the entry:

ext\ext-ejb\classes\content\Language-ext_en.properties

javax.portlet.title.19=Forums

Creating new language entries #

For newly created portlets, it is likely that you will have new language specific text.

Example: Changing the title of a new portlet from "javax.portlet.title.EXT_1" to "Reports". #

Modify your Language-ext.properties file and add the entry:

ext\ext-ejb\classes\content\Language-ext.properties

javax.portlet.title.EXT_1=Reports

Displaying multiple languages in your JSP files #

So now that we know how all these languages are stored and how to overwrite them, the next question we should be asking is.. "how do we display the different languages in our JSP pages?"

You will find this line in the English portal_en.properties file:

use-ldap-password-policy=Use LDAP Password Policy

and this line in the Spanish portal_es.properties file:

use-ldap-password-policy=Utilice la politica de contraseñas de LDAP

To display this text, you would add this line to your jsp:

<liferay-ui:message key="use-ldap-password-policy" />

If you user has chosen to see the Spanish version on your site, it will display Spanish instead of English.

Using the LanguageUtil helper #

The LanguageUtil class can also be used in JSP files to provide a dynamic translation of certain language keys. This class is useful when there are multiple dynamic parameters that needs to be translated:

<%= LanguageUtil.format(pageContext, "back-to-x", pageTitle); %>

The above statement will show the label to return back to a page, with the page title included as an argument. It is also possible to add multiple arguments by passing in an Object array.

Messages that contain HTML syntax need another parameter of type LanguageWrapper, instead of the argument(s) of type Object:

<%= LanguageUtil.format(pageContext, "back-to-x", new LanguageWrapper("<b>", pageTitle, "</b>")); %>

Displaying multiple languages in your Java files #

The LanguageUtil class in Liferay can be used to provide a programmatic translation of certain language keys.

Frequently Asked Questions #

Note: You may have initially found the entry in "Language.properties" and so you may think that you would just need to override that value by editing "Language-ext.properties". However, that will not change anything because all values in "Language.properties" are also in "Language_en.properties" and locale specific definitions take precedence. Therefore, "Language_en.properties" will override any changes you made in "Language-ext.properties". That is why we edited the "Language-ext_en.properties" file.

You edit the same files to change Language Settings, Portlet Titles, Category Titles, Action Names, Messages and any other text that is language dependant.

Related Articles #

The page's current languageId can be pulled from themeDisplay.getLanguageId(), for example

• How to change the language for your Terms of Use Page