ShowTable of Contents
Multilingual Forms Applications
This article will discuss approaches and techniques to develop multilingual forms applications, through two approaches: creating a separate form document for each language, or creating a single form which dynamically changes its labels for each language.
The Multi-Form Approach
In most cases, the best practice is to create a different version of your Lotus Form for each language you would like to present it in. The primary driver is the fact that language differences typically cause a number of layout issues within a given form, and it can be challenging to try and design a single form layout that is dynamic enough to handle all the differences in spacing and sizing required by various differences in language.
The development process to create a set of multilingual forms follows the following steps:
1. Design one form in one language, including business logic. Get this form to as mature a level of completion as possible before proceeding to the following steps.
2. Duplicate the first form and translate the text in the form. Update the form's locale setting to the new locale.
3. Design your forms application to serve the appropriate form depending on the language setting used by the end user. This step depends on the type of application framework being used (for example: servlets or portlets).
4. If requirements necessitate the user can change languages after partially completing the form, the application will need to be built in such a way that the submitted data from the first form can be extracted and populated into the second form in the new language and then sent back to the user. Logic in the form can also be used to flip to the correct page.
In order to make multilanguage Lotus Forms, there are several factors to consider. First and foremost, you need to translate all the text in your form to multiple languages. Second, each form has a locale setting, and this setting determines how currency fields are displayed and in some cases determines formatting on other text, as well as what language a screen reader should use to interpret the text in the form.
Alternate Single Form Approach
The obvious drawback to this approach is that you need now maintain two copies of your form and update both whenever a change is required. A second approach is to design a single form that dynamically contains multiple languages. This can be a challenging solution to develop, so it is best to take into account the following considerations, which are recommended guidelines on when to use this single form approach:
1. Designing a form to handle 3 or more languages dynamically is probably too complex to be worthwhile, if this is the case, consider a one form per language approach described above.
2. Forms with high fidelity printing requirements can be difficult to design with multiple languages in dynamic labels, again, strongly consider the one form per language approach.
To create an application which dynamically switches between languages, we'll follow a two stage approach. The first stage shows how you can design your Lotus Forms such that you can put two versions of text labels into a single form and flip between them. The second stage involves constructing application code (such as a servlet) which allows you to change the locale of the current form by submitting it to a server, changing the locale to a new language, and then sending back the form. A sample servlet is included.
Creating Data Instances for Language Strings
First of all you need to identify and consolidate all of the strings of text which you need to present in multiple languages. Broadly, this includes instructions, labels and warning/error messages. Then you need to design your forms so that they can utilize multiple sets of these text strings, one set of strings for each different language you want to provide in the form.
The underlying XForms technology in Lotus Forms provides you with a great mechanism to accomplish this. You can consolidate all of your strings into an XML structure and then translate all those strings into multiple languages. In your form, you just need to configure it to utilize the appropriate XML instance for the language being used. This can be done dynamically at runtime or prepopulated into the form server side before it is presented to the user.
Here is an example using a variable to indicate dynamically which language should be used in the form. First, you would create two XForms instances, one for English, one for French, like this:
<xforms:instance id="en-CA" xmlns="">
<instructions>Please review and update the following contact information.</instructions>
<xforms:instance id="fr-CA" xmlns="">
<title>INFORMATION SUR LE CONTACT</title>
<instructions>Veuillez réviser les informations suivantes traitant de la personne-ressource.</instructions>
Important: Note that in both instances, the element structure is the same; both contain a <
page1> element, a <
title> element and an <
instructions> element. You should take care to make sure these two structures match, if any of these elements are missing in a language instance, the labels which reference the elements disappear when that language is selected.
In another XForms instance, the locale should be set to match one of the instance IDs exactly. For example, you may want to store the selected language in a logic instance, like this:
<xforms:instance id="Logic" xmlns="">
Once the logic instance is set, you can use it as an XPath reference. For example, in the XForms label where you’d like to display the title "Contact Information" use the language-appropriate XPath reference:
The inner XPath statement: instance('Logic')/locale/selected will resolve first, resulting in the appropriate instance ID, which in turn gets evaluated with the rest of the XPath to the appropriate <
title> element, and the label will show either English or French.
Note: You will need to test your form with each available language and in some cases you may need to use relative alignment to avoid overlapping text since some strings may be of significantly different lengths in different languages.
Creating a Servlet to Switch the Locale Setting
This section will describe how to build a servlet that switches the locale setting of the form. A sample servlet and form is attached to this wiki article.
Lotus Forms have a locale setting which can be changed in the designer by editing the properties for the form global.
Any change to this setting is stored as the xml:lang attribute of the root XFDL element of the document. The root XFDL element looks like this (some attributes are omitted here for brevity):
The approach that should be taken here is to submit the form to the servlet with a URL parameter which specifies the new locale setting you would like to change the form to. The servlet will use the URL parameter and set the xml:lang attribute of the document as well as the element in the "Logic" instance we showed above so that the correct language strings will be used on all the form labels. Once the xml:lang attribute and locale setting in the instance have been set, the servlet will send the form back. By putting XFDL buttons on the form which contain the URL of the servlet and the URL parameter for each of the supported languages, the user can click the button on the form to change their form's language. The example form and servlet which are attached demonstrate these tasks.
- From Eclipse or Rational Application Developer, import the Enterprise Archive file (.ear).
- This will create two projects, one for the EAR (FormLocaleChangeEAR), and one for the WAR (FormLocaleChange).
- The Webform Server framework libraries are not included in the project, you will need to copy them into the lib directory for the servlet to work (this is done so that the servlet is ready for use with any version you have of WFS and also to avoid any potential licensing/legal issues with distributing the framework libraries on this wiki). Follow these steps to install the libraries:
1. Locate the libraries in the Webform server installation directory. These are located in the webform server installation directory in the redist directory. For example, if you used the default installation path, they would be located at: C:\Program Files\IBM\Lotus Forms\Server\3.5\Webform Server\redist
2. Locate the lib directory of your Form Locale Change Servlet project (not the EAR project). In Eclipse or RAD this will be <
3. Copy all of the .JAR files from the redist directory to the lib directory (the .js and .war files they don't do any harm, but they aren't needed and add size)
4. In Eclipse/RAD, click on your FormLocaleChange project and press F5 to refresh it (this will check the directories and notice the updated libraries)
5. Rebuild your Eclipse project.
Deploying to WAS
1. In eclipse or RAD, right click on your EAR project and select "Export..."
2. In the Export dialog, find and select "EAR file"
3. Provide a destination directory and note it for later.
4. Click finish to complete the wizard, thereby generating the EAR file.
5. Login to your websphere application server admin console with an administrator account.
6. Go to the Administration page and select Applications > Install New Application
7. Click the install button.
8. Locate your EAR file on disk and upload it.
9. Complete the deployment steps by following the admin console wizard screens (this may vary depending on your version of WAS and server configuration).
10. Start your application, then access the servlet with the URL http://<
- The Lotus Forms API is not used in this example. If you add any code to the servlet which leverages the Lotus Forms API, you need to make sure the API is installed on your application server or put the StreamingAPI.jar in the lib directory of your project.
- If your webform server translator is located on a different host than your Websphere Application server, you need to modify the web.xml file and change "localhost" to the hostname of your translator server.