Translating Liferay Portal
Alternative Languages: 日本語
Table of Contents [-]
- Step 1) Find out if the translation to the language already exists
- Step 2) Editing the file
- Step 4) Contributing the translation to Liferay (Optional, recommended)
- Other optional steps
This page is about translating the Liferay application. For adding translations of wiki articles, see Translations.
Liferay Portal is an application that can be localized to multiple languages, that even allows each user to choose a different languages of the ones supported by the platform. By default Liferay provides translations to a large number of languages. Some of those translations are reviewed carefully by native speakers although others are automatically translated (you can help if this is the case for you language!).
This article explains how to translate Liferay to a new language or how to improve an existing translation.
Step 1) Find out if the translation to the language already exists #
Liferay maintains the sentences used throughout the portal in a set of files of the form Language_(Language code).properties where (Language code) identifies the language as defined by the Java Internationalization specs.
These files are stored within a directory named 'content' which is deployed to the classpath. The exact location of this directory varies depending if you are looking at the sources or a deployed installation. Here are the most common cases:
- Liferay sources: portal-impl/src/content/Language_(Language code).properties
- Extension Environment: the files are inside modules/portal-impl.jar in the path content/Language_(Language code).properties
- The extension environment allows making changes to these files without actually modifying them by using the equivalent files of the form ext-impl/classes/content/Language-ext_(Language code).properties
- However, you should consider using a hook to override translation keys instead of the extension environment (5.2.x) or ext-plugin (6.x)
- Liferay deployment: within $LIFERAY_WAR/WEB-INF/lib/portal-impl.jar find content/Language_(Language code).properties
- In the Tomcat Bundle: within $TOMCAT/webapps/ROOT/WEB-INF/lib/portal-impl.jar find content/Language_(Language code).properties
Step 2) Editing the file #
The Language_(Language code).properties files are regular text files that can be edited with a simple text editor. Java properties editors available in the most modern IDEs can also be used.
To create the translation for a new language make a copy of the file for an existing language and change the (Language code) to the one associated to the new language. The language code has the following syntax (brackets denote optional portion)
Note that you may have to modify more than one language.properties files. In this page you will find the Location of language.properties
For more information check Internationalization: Understanding Locale in the Java Platform
Dealing with non-ASCII characters (Version 6.x and later) #
Liferay's Language_(Language code).properties files are UTF-8 encoded - this is different from the Java standard, but is an important detail to get your deployment actually working. There's no more transformation required.
Dealing with non-ASCII characters (Only for versions previous to 6) #
When writing a translation to a language that uses non-ASCII characters some problems may arise. This section explains why this may happen and how to solve it.
When using a non-ASCII character in a Language.properties file the text editor will use a different encoding system to be able to represent those files. If the encoding does not match the one used by the portal the non-ASCII characters will not be shown correctly to the user.
While this can be solved by making sure the file is saved with the same encoding, a better way to solve the problem is to encode the file with a Java specific format that is independent of the encoding used. This ensures that even if the encoding used by the portal is used the non-ASCII characters will still be read correctly.
Java provides a command line tool called native2ascii that allows converting from any encoding (specified as a parameter) to Java's format. Liferay uses this tool for all languages that need it (actually, all but English). It stores the files with the original encoding with the extension .native and the does a conversion:
Language_(Language code).properties.native ==> Language_(Language code).properties
As a conclusion, if you are using liferay 6 or newer you don't have the native files and you don't have to worry about the non-ASCII characters at all. Otherwise:
- When editing Language files within Liferay's sources or in the Extension Environment never edit the Language_(Language code).properties files directly. Instead edit Language_(Language code).properties.native.
- When editing them in your own environment we recommend using a similar pattern, modifying the .native files (or whatever extension you like) and using native2ascii' to generate the actual Language file
- You only need to deploy the files of the form Language_(Language code).properties (without the .native extension)== Step 3) Installing the new or modified translation ===== Modified translations ===
The recommended way to immediately use an updated translation is to deploy the modified language keys through a hook. This way your translation contains only the entries that differ from Liferay's default translation to the language that you modify. A hook is hot-deployable, so you can update the translation without restarting the portal. Also, you can easily upgrade the portal without affecting your changes - on update you can check if your modifications are still necessary (see the paragraph about contributing your translation back below)
New Translations #
Once you have a new translation file they should be placed along with the other Language files in the locations listed in step 1. (They can also be deployed as a hook - see above)
If it is a new translation it will also be necessary to register it within Liferay. To do that you'll have to:
- edit your portal-ext.properties and add the new language to the property locales. For example to add
- edit ROOT/WEB-INF/web.xml and add URL mappings for your language:
<servlet-mapping> <servlet-name>I18n Servlet</servlet-name> <url-pattern>/lt/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>I18n Servlet</servlet-name> <url-pattern>/lt_LT/*</url-pattern> </servlet-mapping>
Step 4) Contributing the translation to Liferay (Optional, recommended) #
To contribute your translation back to liferay, so that it can be included in future versions of the portal, please login to http://translate.liferay.com (use the same credentials as on www.liferay.com). We're using that site for contributions to our translations.
You might also consider to introduce yourself and participate in the translations forum.
Other optional steps #
- Change the default language for new users: Read steps in Language/display customization