In this tutorial, you’ll learn how Liferay facilitates generating language key files and translating the keys to languages you want to support. In order for a user to see a message in his own locale, the message value must be specified in a resource bundle file with a name ending in his locale’s two character code. For example, a resource bundle file named
Language_es.properties containing a message property with key
welcome must be present with a Spanish translation of the word “Welcome.” Don’t worry, the Plugins SDK provides a means for you to get translations for your default resource bundle.
It’s time to get started by doing the initial setup for the Microsoft Translator service for translating the language properties.
Translating Languages Using the Microsoft Translator
The Plugins SDK uses the Microsoft Translator service http://www.microsoft.com/translator/ to translate all the resources in your
Language.properties file to multiple languages. Since it’s a machine-generated translation, you can use it as a base translation for you to start with. To create base translations using the Microsoft Translator service, you’ll need to do the following:
Sign up for a Microsoft Azure Marketplace account.
Purchase a subscription to the Microsoft Translator.
Register your portlet as an application in the Azure Marketplace. You can do this from the Developers screen in My Account. The client ID needs to match the project name of the portlet. Accept the default client secret. Make sure to save the client ID and client secret for later use.
build.[username].propertiesfile in your Plugins SDK root directory, if you don’t already have one. This
build.[username].propertiesfile must reference a Liferay bundle. If you have a Liferay Tomcat bundle, for example, your reference should look like this:
app.server.dir=[Liferay Home]/tomcat-7.0.42 auto.deploy.dir=[Liferay Home]/deploy
[Liferay Home]refers to your bundle’s root directory.
Make sure that you have a
portal-ext.propertiesfile in your Liferay Home directory. Create it if you do not. Edit the
portal-ext.propertiesfile, adding the following two lines replaced with your values for the Microsoft Translator client ID and client secret portal properties:
Next, you’ll make the necessary changes to your portlet so that it can leverage the Microsoft Translator service.
Implementing Translations in Your Portlet
Now that you’ve done the initial setup for the Microsoft Translator, you’re ready to add support for translations to your portlet.
In your portlet’s
docroot/WEB-INF/src/content/Language.propertiesfile, add your language keys. For example, you may enter a key like this one:
you-know-it-is-the-best=You know it is the best
Translations are only generated for properties that have not been translated previously.
Make use of your language keys in your JSPs. For example, you can specify language keys in
<liferay-ui:message>tags, as demonstrated in the following JSP code:
Liferay - <liferay-ui:message key="you-know-it-is-the-best" />!
Tags like the above
<liferay-ui:message>tag look up the value of the language key for the current locale and render it for the user.
For example JSP code that references language keys, see
Build the language keys, by either right-clicking on the
Language.propertiesfile → Liferay → Build Languages in Liferay IDE/Developer Studio or by running
ant build-langfrom your plugin project’s directory in your terminal.
When the build completes, you’ll find the generated files with all the translations in
Language_*.propertiesfiles in the same folder as your
Language.propertiesfile. Note that many of the language properties files don’t contain translations. This is because they are intentionally disabled. We decided to do this because several of the translations are “suboptimal, rude, hilarious, or wrong,” according to this ticket. You’ve been warned: it is a machine-generated translation.
Switch your portal’s locale to the language for which you want to see the translated language properties. For example, you can switch to Spanish by adding
localhost:8080and refreshing the page. Notice how your portlet shows your translated language keys.
After you’ve generated an initial translation for a language property (i.e., key/value pair), the assumption is that you’ll manually make any updates that those translated values require. On subsequent builds of the language properties, the language builder intentionally leaves existing language property translation values alone, so as to not overwrite any of your manual translation work. That said, if you want to generate new translations of an existing property you must first remove that property from
Language.properties, build the languages (to remove the property from the
Language_*.properties files), re-add that property and its new value to
Language.properties, and build the languages again. At this point, Microsoft Translator generates translations based on your property’s new value.
By using the Plugins SDK’s language building capability, you can keep all created translations synchronized with your default
Language.properties. You can run it any time during development. It significantly reduces the time spent on the maintenance of translations. However, remember that a machine translation is generated by the Microsoft Translator. Machine translations can often come across as odd, rude, or unintentionally humorous. Sometimes they are simply inaccurate. Someone fluent in each language should review the translations before the translations are deployed to a production environment.
In this tutorial you learned to leverage the Plugins SDK to generate translations for your portlets using the Microsoft Translator.