Introduction
WebRatio Platform provides a built-in feature for the localization of Web applications.
The localization is based on the usage of keys instead of terms for all the static elements of the Web application (e.g., labels, components and page titles, field labels and so on). WebRatio Platform allows users to define several locales and to provide the translated messages for each key for each locale. At runtime, keys are replaced with the provided messages for a specific locale. With this structure of keys and related translations it’s possible to realize a Web application without being concerned about the particular languages the application must support, due to the complete separation between the model and locale management.
How to enable the localization
When you work with a Web Project, by default it is not localized. You have to explicitly enable this feature. You can decide which are the sections of your Web application to be localized thanks to the View Container concept. In fact, you can set the Localized property in the Property View for each view container you desire (site view, area or page). Refer to the "View Container" online lesson for further information. The property affects all the view container content.
Once the localization is enabled, you have to:
- Define which locales to manage.
- Provide translated messages for all proposed keys in each locale.
- Define patterns for each data type in each locale.
- Decide where translations must be stored.
- Design an administrator section for messages management (optional).
How to add a new locale
A locale is a set of parameters that defines the user's language, region and any special variant preferences that the user wants to see in their user interface. Usually a locale identifier consists of at least a language identifier and a region identifier. (source Wikipedia https://en.wikipedia.org/wiki/Locale_(computer_software) ).
WebRatio Platform supports the definition of a lo1. Define which locales to manage1. Define which locales to managecale by using two different information: the language iso code and the country iso code. The language iso code represents a specific language (e.g., english, italian, spanish and so on) while the country iso code specifies which is the geographic place associated to a language (e.g., United States, United Kingdom, Italy, Spain and so on). You can find the complete list of codes here. Using this strategy you can specify different translations for the same key for the English [United State] and the English [United Kingdom] locales, if necessary.
The definition of a new locale is performed through the Localization Dialog. Here you can add, edit and delete all the locales defined in your Web Project. By default you get one locale, which is the English [United States] one. This is why it is strongly suggested to label model elements in english and then translate everything in all other required languages. Nevertheless, it is possible to delete the default locale and add your own ones. This is the procedure to add a new locale:
- Open the Localization Dialog by pressing the Localize button in the main toolbar.
- Right-click on Locales and select the Add > Locale option.
- In the opening dialog choose the locale you want to add (e.g., Italian[Italy]).
- Press the OK button to confirm.
You also have the chance to create a new locale starting from an existing one. This option is useful when you have two locales that are very similar and differs for few messages only. You have to:
- Open the Localization Dialog by pressing the Localize button in the main toolbar.
- Right-click on the locale you want to copy and select the Duplicate… option.
- Choose the locale you want to add (e.g., Italian[Switzerland]) from the opening dialog.
- Press the OK button to confirm.
At the end of the procedure you get the new locale along with all messages translated as the one you started from.
The default locale
WebRatio Platform adds by default one locale to your Web Project. It is the English[United States] locale, which contains all the labels of the project. Those labels are used as terms shown in the Web application until you enable the localization. This locale is also set as default, which means that when there is no locale corresponding for the particular language used by a user, the application uses the default locale for messages. You can set which is the default locale of your project when you have more than one locale.
How to set a locale as default
The presence of a default locale is mandatory. You can set a locale as default following these steps:
- Open the Localization Dialog by pressing theLocalize button in the main toolbar.
- Right-click on the desired locale and select the Set Default option.
You can see that a blue triangle is shown in the locale icon to specify that it is the default one.
How to write translated messages
Once you defined all required locales, you can proceed with the keys translation into messages. This is a long and quite annoying work, but the usage of some conventions can speed it up. WebRatio Platform also helps you grouping keys depending on the referenced model element and providing the translated messages for some of them (e.g., Components and Validation Rules).
Let’s talk about some useful conventions:
- Write model elements name in one language (e.g., english).
- Write model elements using the same format (e.g., camelcase, lowercase).
- Write model elements representing the same concept in the exact same way.
The last two points are very important because keys are case sensitive, so it can happen that you translate twice the same key because of the different format.
The translation of keys can be done at design time or at runtime. At design time, you as the modeler are in charge of this work. You can use the Localization Dialog at this purpose. At runtime, you can ask a professional translator to do this work. Read the "How to manage translated messages at runtime" section to learn more.
These are the steps necessary to add a translated message:
- Open the Localization Dialog by pressing the Localize button in the main toolbar.
- Select the locale you want to manage from the list on the left.
- Select the Messages tab.
- Select the All item from the second column.
- You can see on the right all the keys related to the current selected locale.
- Select a key from the list and write the translated message in the Message column.
If a key coincides with the message for a locale, you can use it as message. You just have to right-click on the key and select the Set Default Messages option.
- Press the OK button to confirm.
How to define custom messages
Whenever you need to provide a localized message concerning an element not present in the model, such as keys used directly in layout templates, you need to add a Custom Key to the keys set of your project.
- Open the Localization Dialog by pressing the Localize button in the main toolbar.
- Select the locale you want to manage from the list on the left.
- Select the Messages tab.
- Right-click on the Custom item in the second column and select the Add Custom Key option.
- Write the key and the message you desire in the opening dialog.
- Press the OK button to confirm.
From now on the custom key can be used in every locale.
How to use custom messages in templates
Custom keys and related messages are usually created to be included in layout templates. The "WRDefault" style use custom messages for showing a text to the user when a component does not have content to show. You can refer to the "WRDefault" style for working examples. The best way to use custom messages in layout templates is the following:
- Declare a Layout Parameter with the custom message key as a value. You can also set a default key as in the following example.
<wr:layoutparameter default="emptyUnitMessage" label="Empty Unit Message" name="empty-unit-message" type="string">
Defines the key of the message to use if the unit is empty.
Default value: emptyUnitMessage
</wr:layoutparameter>
- Retrieve the value of the Layout Parameter using a Groovy code fragment
def emptyUnitMessage = params["empty-unit-message"]
- Print the custom message key in the template using the <bean:message> JSP Tag, which is the tag that writes the translated message associated to the provided key for the current locale. The key is stored in the emptyUnitMessage variable. The printJSPTagValue Groovy method is used to avoid the escaping of some special characters that might be included in the key, since you want the key to be print it as is in the JSP page.
<bean:message key="[%printJSPTagValue(emptyUnitMessage)%]"></bean:message>
How to define patterns
Besides messages it is possible to define patterns related to each locale for the visualization of data types such as boolean, date, time and so on.
- Open the Localization Dialog by pressing the Localize button in the main toolbar.
- Select the locale you want to manage from the list on the left.
- Select the Patterns tab.
- Select the data type you desire (e.g. date).
- Configure the pattern as desired.
- Press the OK button to confirm.
Pattern must be expressed using the Java patterns. If you need more information about how to set up a pattern for a data type you can refer to this online documentation:
- date, time and timestamp. These data types use the SimpleDateFormat Java class. Please refer to this link for further information.
- decimal, float and integer. These data types use the DecimalFormat Java class. Please refer to this link for further documentation.
How to manage subtypes
The Localization Dialog has a dedicated section to set patterns for subtypes. A subtype is a user-defined data type used for attributes in the Domain Model. You create a subtype when you want an attribute to have a specific pattern which is different from any of the default ones. These are the steps to add a subtype to your project:
- Select the Domain Model tab in your Web Project
- Right-click in the work area and select the Add > Subtype option.
- Move to the Properties View, write a name for the subtype (e.g., Currency) and select a data type in the Type property.
Once you defined a subtype, it is reported in the Subtypes group of the Patterns tab in the Localization Dialog.
How to use patterns in layout templates
Let's suppose that, for some reason, you have an information which is represented always as a string. This information may contain a number, a string or a date and you want to show it to the user with the proper format. What you need to do is this:
-
Store the string information in a variable that can be accessed from the pageContext. You can use the c:set JSTL Tag at this purpose. In this example the information is contained in a Details Component and the Component State Object property is "information".
<c:set var="stringdata" value="${<wr:Id context=”unit”/>.data.information}"/>
- Retrieve the "stringdata" variable from the pageContext in JSP and create a new variable using the proper data type. In this example the "stringdata" variable contains a date.
<% String stringvalue = pageContext.get("stringdata");
pageContext.setAttribute("datedata", java.sql.Date.valueOf(stringvalue ));%>
- Print the new variable "datedata" as a date using the proper JSTL Tag. You can find more information about the fmt library here. In this example the used tag is the fmt:formatDate. What you need to know to properly write the tag is the name of the variable containing the pattern for the desired data type. WebRatio Platform uses the following naming convention: <datatype> Pattern. So, to print out a date the variable to use is "datePattern".
<fmt:formatDate value="${datedata}" pattern="${datePattern}"/>
How localization works at runtime
Localization at runtime is managed by two context parameters present in your Web Project: the CountryISOCtxParam and the LanguageISOCtxParam. The value of these context parameter decides which is the used locale and so which is the language of the translated messages.
When the user access a page, these context parameters are set with the Web browser preferred languages. The Web application then searches for the locale identified by the ISO codes contained in the context parameters to show the proper labels. If there is not a corresponding locale, the default locale is loaded and all the keys contained in the page are substituted with the corresponding message of that locale. In this way the application uses the appropriate local for every user.
How to change the locale on the application
In many cases the default locale set in the browser and used to navigate the Web application is different from the one desired by the user. It is possible to give to the user the chance to explicitly choose the desired locale among the available ones directly from the Web application. Of course, you need to model this feature in the Web Project. The model is composed of a list component showing the available languages in a list and an action definition containing a reset operation that changes the value of both LanguageISOCtxParam and CountryISOCtxParam to the user selection ones.
How to manage translated messages at runtime
In the "How to write translated messages" section your learnt how to set messages at design time. This means that every time you add, change or remove a message you need to work in the Localization Dialog and generate the Web Project to apply the changes.
Sometimes you may have the need to fix a label at runtime, for example due to a typo error, and you do not want to deploy a new version of the Web application for this reason only. What you can do is to fix the label in the deploy package and then bring the change back in the model using the Localization Dialog. Another option is to have a dedicated section of the Web application dedicated to the messages translation, so that a specific user can access it and make the required changes and corrections. Let’s see in the following sections how to handle these two different situations.
How to manually change a message in the deploy package
Localization messages are stored in dedicated files. These files are named "ApplicationResources_<ISO Language code>_<ISO Country code>.properties" and are located in the "WEB-INF/classes" directory of your Web application deploy package. If you want to change a message you need to:
- Identify which is the ApplicationResources file containing the message to be changed.
- Open this file with a text editor.
- Search and change the desired message.
- Save the file.
- Reload the Web application.
How to store messages on database
The prerequisite to model a "Message Management" section is that all messages are stored inside a dedicated table on the database and not in files as explained in the previous section. You can change the message storage in this way:
- Select the Project tab.
- Move to the Properties View.
- Select the Localization tab.
- Choose “Database” option for the Bundle Store Type property.
- Press OK in the confirmation dialog shown.
- Write a time in minutes for the Bundle Refresh Timeout (optional).
At the end of the procedure you obtain a "Bundle Data" entity in the Domain Model. This entity is composed of:
- Locale. The attribute representing the locale belonging to each message, written in the format "language_country".
- Key. The attribute containing the key of the label.
- Message. The attribute containing the translated message.
This entity must be synchronized to your connected database. Watch the "Connecting the Database" online lesson to learn how to do it.
Once you have this entity properly configured you can fill it in with the messages you already translated in the Localization Dialog. This operation must be done at runtime in a dedicated Web application section which is automatically generated by WebRatio Platform, once you enable it. This is the required procedure:
- Select the Project tab.
- Move to the Properties View and select the General tab.
- Enable the Enable Admin Area option.
- Use the Generate Full Web Project command to generate the project.
Once the Web application has been generated you can access this restricted section to fill in the Bundle Data entity with current translated messages:
- Enter http://<application-url>:8080/WRAdmin/Home.do
- Enter "manager" as username and "m4n4g3r" as password and press the Login button.
- Search for the "Localization" section of the page.
- Press the Update Bundle Data button to fill in the table.
When the operation completes you can see the message
"The database bundle data is aligned with the model".
You can repeat these steps every time you add a new key from the Localization Dialog. This procedure does NOT work if you change messages or delete keys from the dialog. You must do these operations directly on the "Bundle Data" table. Also for this reason you have to model a dedicated section of your Web application to manage messages.
How database storage is used at runtime
The Web application must retrieve all messages related to a locale from the dedicated database table. This operation must be done for each label shown in a page and it can be very expensive in terms of performances because a query is done for each label for each user request. At this purpose, there’s a memory storage mechanism that loads all labels in the application memory, which is shared among all users and which is fastest to access. This is why you must set a timeout used to reload the labels and update them with the last changes done on the database table.
How to model a "Message Management" section
Once you moved the messages on the database, you can model a dedicated section of your Web application that let the user enter proper translations. You can refer to the following image for an example.
The idea is to have a couple of entities for the messages management: the first one is the "Bundle Data" entity introduced in the previous sections: the second one is the "Language" entity which contains all desired languages along with their iso codes. You can also include unused languages in this entity and manage the active ones through the "enabled" attribute.
The "Message Management" page lets the user search messages to be translated using language, key and messages as search criteria. Then, a Multiple Form presents the matching results so that it’s possible to write proper translations. Refer to the "Advanced Data Management:IFML Model" and "Advanced Data Management: Action Definition" online lessons for further information. Finally, the "Save messages" action refers to an action definition that updates the messages using an update operation.
How to use the sample project
You can use the "LocalizationSample.zip" file attached to this article, to test the "message management" model proposed previously.
Follow these steps to use the project:
- Import the sample project in WebRatio Platform. You can learn how to do this by watching the "Organize the Workspace" online lesson.
- Using MySQLWokbench or external software that allows you to manage the database, create a new empty database named, for example, "localizedb" (if you not using the WebRatio Community Platform version).
- In WebRatio Platform, open the project and go to the "Domain model" tab. In the Outline View select the "DB" node and move to Properties View. You can change properties with your local mySQL database settings (URL, Username, Password). You can learn how to do this by watching the "Connecting the Database" online lesson.
- Execute the script files present in the project. Move to WebRatio Explorer View, and expand the project node and then the "DBScripts" folder. Execute the "script_tables.sql" file and then "script_data.sql" one. You can execute these files, right-click on the file, select the "Execute sql.." option and then press "OK" button to confirm.
- Generate the project with the "Generate and Run on Cloud" command if you have a WebRatio Community Platform version; otherwise, use the "Generate and Run" command.
- Visit the Administration area to load the Bundle Data. Refer to the procedure explained in the "How to store messages on database" section in this article.
- Visit http://localhost:8080/LocalizeSample/ or http://freeXXXXX-freeapp.eu.webratio.net/ with any browser, and follow the instruction to test the operation.