Calendar
Calendar Admin and Calendar View
The Calendar Admin and Calendar View correspond to the calendar-admin.war and calendar-client.war artefacts.
These two modules use the RequireJS i18n framework, for handling translatable GUI elements. This framework can be found at http://github.com/requirejs/i18n and is available under both the MIT and new BSD licenses.
This section describes how to add new translations to these modules. It will not cover the actual usage patterns of the require.i18n framework in javascript code, as that is out of scope for this section. For more information on that topic, please consult the require.i18n documentation.
General structure of require.js translations
Translations in the calendar-admin and calendar-client modules are based on language files bundled into the compressed ".war" artefacts. In the root of the war archive there is a 'nls' folder which contains a number of folders and a single strings.js file:
All sub-folders except the 'root' folder contains the .js file for a particular language as specified by the name of the folder using the standard 2-letter language code, e.g. ar = Arabic, de = German, sv = Swedish etc.
The 'root' folder contains the default translation, in the context of these calendar modules, we use English as the 'root' language.
The strings.js file is used to declare all translated languages:
Inside each language-specific folder, the actual translation file is placed, always named strings.js. Please note that these translated files are NOT the standard message-bundle property format with simple key-value pairs. Instead, require.js uses JSON (JavaScript Object Notation) structured files in order to be able to group translation key-value pairs into hierarchical groupings:
The document starts with a require.js define(..) function call whose single argument is a JSON document. As seen above, this JSON document has a root element named 'calendar' with a number of sub-elements both being other JSON objects but also plain key-value pairs. For example, we see the 'button' sub group of translated values where translated button names have been grouped together. We also see usage of arrays such as the 'dayNames':[…] array where a translated name for each day of the week can be specified for a given weekday index.
The isRTL and firstDay properties
The calendar.isRTL and calendar.firstDay properties have a special meaning in the context of the calendar-admin and calendar-client applications.
• isRTL: [true|false] is used to determine whether the web application should be rendered from left-to-right or right-to-left. So, for an Arabic translation, one would set 'isRTL':true, while Swedish, for example, would use 'isRTL':false
• firstDay: [0-6] is used to denote which day of the week that is the first day of the week. 0 == Sunday, 1== Monday … 6 = Saturday. This affects the calendar-admin Week Schedule and the calendar-client weekly view where one manages appointments. You do not need to change the 'dayNames', 'dayNamesShort' etc. array indexing if you change firstDay.
Step by step guide for adding a new translation
Given the general information stated in the previous section, a step-by-step instruction to add a new language to either of the calendar-admin.war or calendar-client.war could be (using calendar-admin.war as example):
1. On the file system of the Orchestra server, find the 'calendar-admin.war' file. The calendar-installer will place this file in %QP_HOME%/deploy.
2. Copy the .war file to a temporary location such as c:\qmatic\temp and extract the .war file using 7-zip, WinRAR, or similar. To unzip or jar xvf calendar-admin.war on a Linux command shell. You should see something similar to the screen shot below:
3. Open the 'nls' folder
4. Create a new folder named as the 2-letter code of the language you want to add, for example 'sv' for Swedish.
5. Open the root folder and copy the strings.js file into your new sv folder.
6. Open the strings.js file in the nls folder with your favourite text editor and add an entry for 'sv'
7. Open the strings.js file you previously copied into the new 'sv' folder.
This way, you have the full structure laid out with the default English translations in place.
8. Now you can just go ahead and start to translate each value one-by-one.
9. When you are satisfied with your translations, please make a copy of your new strings.js so you do not lose it.
10. Now it is time to repackage the calendar-admin.war with the new translation added. You can do this in several ways:
a) One could use a utility like 7-zip to just copy the full 'nls' folder into the original calendar-admin.war which would add or overwrite the necessary files:
b) Another method is to use the c:\qmatic\temp folder created in step 2 of this guide, which contains all the content of the original calendar-admin.war plus the original calendar-admin.war archive file. Select all files except the calendar-admin.war and use 7-zip (or similar) to create a new calendar-admin.war archive. (Remember that a Java.war/.jar/.ear is just a standard zip file with another suffix).
c) One can also use a command-line tool such as the Java jar program to create a new calendar-admin.war. Remember to not include the original calendar-admin.war in the new archive:
11. In the final step, it is time to redeploy your updated
calendar-admin.war artefact into Orchestra. For more information, see
“Redeploying Applications” .
12. After the artefact has been redeployed, you can test your new translation. You may need to make sure that you set your web browser's preferred language at the top of the languages list, example from Internet Explorer 11 (Swedish):
Contrary to other Orchestra modules, the calendar-admin.war and calendar-client.war do not use the language set on a user in Orchestra, they solely use the browser's language preferences.
Appointment Terminal
The Appointment Terminal language support is very similar to the standard solution used in Orchestra modules, the only difference actually being where the language bundle file is stored. Normal Orchestra modules always read language files from %QP_HOME%/conf/lang, see below:
However, the appointment-terminal.war archive bundles its own language file in a folder named bundle:
By default, the bundle folder contains a single file named appointmentTerminalMessages.properties, which is a translation for the default language.
Step by step guide for adding a language to the Appointment Terminal
1. To create a new translation for the Appointment Terminal, follow steps 1 and 2 from the calendar admin / calendar-client guide,
“Step by step guide for adding a new translation” , extracting the
appointmentterminal.war file into a temporary folder.
2. Make a copy of the bundle/appointmentTerminalMessages.properties file and name it with the language suffix of your desired language such as appointmentTerminalMessages_sv.properties for Swedish.
3. Open the new _sv file in your favourite text editor.
4. Now start replacing the default English translations with the ones for your own language.
5. Finish by following the steps 9-12 from the calendar admin / calendar-client guide,
“Step by step guide for adding a new translation” , to repackage and redeploy the
appointmentterminal.war artefact. Remember to make a backup copy of your new translation file, as a later upgrade of Orchestra with new versions of
.war artefacts would overwrite your own translations.
