Localization

Language settings

There is no need to rebuild the application for a particular language. When the application is built, all the messages files in all the available languages are included. The default locale can be changed by setting the application property unitime.locale through the Administration > Defaults > Configuration page.

unitime.locale=en

For a particular http session, the locale can be also changed using the locale parameter, e.g., see our online demo in Czech: http://demo.unitime.org/UniTime?locale=cs. Please note that only some portions of the application were made localizable (and have Czech translations) so far.

It is also possible to tell the application to take the language settings from the browser. This is done in the LocaleFilter, when the use-browser-settings parameter is set to true (e.g., by web.xml)

Implementation Details

Most of the UniTime application was written using Apache Struts, however, new pages and components (and in future the whole user interface) are written using Google Web Toolkit (GWT). For localization of GWT parts we use its i18n capabilities.

In short, all text messages are put into a Messages interface (e.g., see StudentSectioningMessages) which is then used by calling these methods on a class created calling GWT.create(message interface), e.g., see this widget. Note that this only works in the client code (the code that gets compiled into JavaScript), however, for the server side we have created a very similar approach so that the created Messages interfaces can be reused as we move more towards GWT in the future. We use this technique for both server side of the GWT-based pages and components as well as for the old Struts-based pages and JSPs. For server-side Java code (e.g., Struts forms and actions), the only difference is that the Messages class is instantiated using Localization class (e.g., see here). In Java Server Pages (JSP) files, we have two tags <loc:bundle/> and <loc:message/> that are providing the localized strings (e.g., see here, the tags are defined here).

<%@ taglib uri="/WEB-INF/tld/localization.tld" prefix="loc" %>

<loc:bundle name="CourseMessages">

<%-- translated message, using loc:message, e.g.,

titleRemoveRoomPreferences=Remove Room Preferences

-->

<loc:message name="titleRemoveRoomPreference"/>

<%-- translated message with one argument, e.g.,

labelConfiguration=Configuration {0})

-->

<loc:message name="labelConfiguration"><bean:write property='configName'/></loc:message>

<%-- translated message, using MSG property -->

<%=MSG.confirmRoomSizeDifferentFromCapacity()%>

<%-- additional message bundle -->

<loc:bundle name="ConstantsMessages" id="CONST">

<loc:messsage name="monday" id="CONST"/>

<%=MSG.sunday()%>

</loc:bundle>

An example of using localization tags in a JSP file

protected final static CourseMessages MSG = Localization.create(CourseMessages.class);

...

// Throw a localized exception if the user is not logged in

if (!Web.isLoggedIn(request.getSession()))

throw new Exception(MSG.exceptionAccessDenied());

// Localized message

MSG.listInstructors(department.getDeptCode(), department.getName())

An example of using localization in a Java file

public static final StudentSectioningMessages MESSAGES =

GWT.create(StudentSectioningMessages.class);

// Localized button

// buttonRequests=<u>R</u>equests

iRequests = new Button(MESSAGES.buttonRequests());

// Localized message with multiple arguments

// backToBackDistance=Distance to travel from {0} is approx. {1} minutes.

MESSAGES.backToBackDistance(clazz.getBackToBackRoom(), clazz.getBackToBackDistance()

An example of using localization in a GWT client code

Here is an example of a change localizing a particular page. The default messages are in English, the language-dependent messages are in a property file with the same name (plus identification of the language using two character iso language code), e.g., see Czech translation of CourseMessages.

Translation Files

Struts localization files are available in org.unitime.localization.messages package, GWT localization files in org.unitime.timetable.gwt.resources package.

Also, please take a look at classes ExportMessages and ImportMessages that can be used to convert existing messages to a CSV file and back -- the file can be easily edited in Excel (or Google Docs) -- it has three columns: message name, English (default) variant and localized variant. One of the first steps could be translating these course messages to your language and trying to plug them in.

Course Messages Localization Example

Example of the localization files in Google Docs.

Note that the language has to be added in the UniTime.gwt.xml (as a supported language, extending locale property) for the GWT compiler to create the appropriate language mutation.

Zanata

A project has been created at zanata.org to support the cooperation of users on the translation of UniTime to other languages. Please note that if you want your translation to be a part of the standard distribution of UniTime, you need to sign a contributor license agreement for Apereo.

With Zanata, you translate all the messages at https://translate.zanata.org/iteration/view/unitime/4.5. To test the translation in your version of UniTime, you will need to

Have a local clone of the UniTime repository (git clone https://github.com/UniTime/unitime.git)
In Zanata, under User Settings > Client, generate an API key (if you have not done so) and copy your Configuration (zanata.ini) to ~/.config/zanata.ini
Download translations from Zanata either using
- Zanata client
  1. Install a Zanata client on your computer (see http://docs.zanata.org/en/release/client for more details)
  2. Pull the translation from the project (e.g., by calling zanata-cli pull in your local UniTime repository). This should download the translation files under Documentation/Translations.

- - or using Maven (zanata:pull task)

- 1. Pull the translation from the project (e.g., by calling mvn zanata:pull in your local UniTime repository). This should download the translation files under Documentation/Translations.

Import translation by using Apache Ant, import-translations task (ant -Dlocale=cs import-translations), which will populate the above-mentioned files with messages with the translations from Zanata for the given locale.
Build UniTime (using either ant build or mvn package)

Note that if you are importing a new language, you will need to include the two character language code in the UniTime.gwt.xml (extending locale property).

Notes

If you want to help with translation to another language, please consider looking at the English dictionary, which contains terminology used in UniTime in the original English version. It is advisable to start by translating these terms first, then fill in the translation of particular messages (in Zanata or elsewhere).