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.
The Plugins SDK uses the Microsoft Translator service
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.
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
the languages (to remove the property from the
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
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.