Simple multi-lingual forms using Domino

Erwin van Hunen & Mark Leusink, 4 November 2003

Category: Forms; Keywords: Language translate

Your customer wants a multi-lingual Domino web application that is able to switch languages in real time. Furthermore, it has to be possible to add and edit languages without much hassle. Besides that, your customer doesn’t want to invest in additional tools, so you can only use the Domino Designer.

The end result of the application has to look like the forms below. First, the form in English:

And the form in Dutch:

Solution:

As the customer doesn’t want to invest in any additional tools (neither licenses nor time to learn a free tool) you will have to stick to Domino Designer. Fortunately for us this is not going to be as problematic as you might first think.

One solution would be to create a form or a view for every language. But imagine the number of design elements in your database if you did this! Furthermore, you will have to do some fancy trickery to make sure the system uses the correct form for the specific language.

Another, much simpler (at least, that’s what we think) solution would be to make one form, and put all the languages on that form. Not using hide-whens, but using a more centralised and structured approach.

Let us try to explain the concept of our solution step by step:

Create a multi-value, computed-for-display field on every form for each language. Call this field TransXX, where XX is a language code, e.g. TransNL or TransEN for Netherland and England respectively. These fields are going to hold all text elements you want translated.
Create a multi-value, computed-for-display field on each form called TransID: this field is going to hold an identifier for every text element specified in 1.
Note that the position (list index) of an ID in the TransID field has to be same as the translated text in the TransXX fields, since we’ll be using this position later.

Let’s try to explain this somewhat further. Take the following form as an example

In the form above, several textual elements can be recognised. In the table below I have assigned them an ID and also translated them into Dutch

ID	English	Dutch
FillIn	Please fill in the following fields	Vul de volgende velden in a.u.b.
Name	Name	Naam
Address	Address	Adres
Telephone	Telephone number	Telefoonnummer

Now I create the fields as described above, being TransID, TransEN and TransNL. These fields are all “Computed for Display”, multi-value fields. The values I put in these fields are listed below.

TransID
“FillIn”,
”Name”,
”Telephone”

TransEN
“Please fill in the following fields”,
”Name”,
”Telephone number”

TransNL
“Vul de volgende velden in a.u.b.”,
”Naam”,
”Adres”,
”Telefoonnummer”

Glueing it all together:

This whole method is glued together with what we call the “TransApplied” field. The TransApplied field is filled in when the form is opened by reading a) the the current language and based on that, b) the translated text elements in one of the TransXX fields.

When you need a text label on your form/document/view, you do a lookup in the TransID field, to find the label with a specific ID and retrieve its position in the list (index). After that you can retrieve the translated text from the TransApplied field at the looked up index.

There are different options to read the language that must be displayed. To name a few:

Using a URL parameter (http:///database.nsf?open&lan=NL”;
Retrieving it from the “HTTP_Language” CGI Variable or;
By setting a cookie somewhere in your application.

The language field in our sample database is filled with an @Formula (notice this is R6 only, although it can be done in R5 as well):

URLLanguage := @UrlQueryString("lan");

BrowserLanguage := @Left(@GetHTTPHeader("Accept-Language");2);

DefaultLanguage := "EN";

@If(

URLLanguage != ""; URLLanguage;

BrowserLanguage !=""; BrowserLanguage;

DefaultLanguage

);

What this formula does is read the “lan” parameter from the URL. If it cannot find it, it will get the Accept-Language header line from the HTTP Header. If it cannot find that, it will revert to the default language code: EN. Again, like the fields above, the Language field is computed-for-display.

So now we have figured out the language to use, it’s time to fill the TransApplied field, which will contain the translation which is going to be used on the form. The TransApplied field has the following formula as its value:

In Domino 6:

@GetField("Trans"+Language)

In Domino 5:

@If(

 Language=”NL”; TransNL;

 Language=”EN”; TransEN; 

 TransEN

);

Now we have several fields on form already, but still no actual text labels. You will have to modify your form in such a way that everywhere you want a text label, you create a <Computed Value> (or a computed-for-display field).

The computed value contains this formula:

In Domino 6:

ID := "Fillin";

ListLocation := @Member(ID; TransID);

TransApplied[ ListLocation ]

In Domino 5, change the last line to: @GetMembers(TransApplied; ListLocation)

Note: @GetMembers is an undocumented and pretty handy @formula, you can achieve the same result using @Subset.

Let us describe what goes on when you open a form/document/view:

You open the form in a webbrowser;
The ‘form’ checks if you have specified a lan parameter;
If so it will use that as a language setting, if not it will check if your browser specified an accept-language header. If not it will revert to a default language;
The form will work out the corresponding translations from the TransXX field and will put those fields in the TransApplied field;
All the labels will show up using the correct language.

Following is a screen shot of a ‘translated’ form in designer mode:

What about views? It can be done using this method: we did that to. Just a small howto:

Make sure that the TransApplied and TransID fields are available as hidden HTML fields;
Create your own javascript function which returns and writes (‘document.write’) the correct translation given a certain id;
Instead of writing a column header in a view do a call to this javascript function which will then write out the correct translation.

Furthermore, radio button field values can also be done. There’s an example in the database to show you how.

Conclusion:

We fully understand that you might be a bit confused reading all this stuff about TransID, TransEN, TransNL and TransApplied fields. That’s why we’ve included a database that you can download and check out to see how it works in a live situation. Once you understand how it works it’s really simple to make multi-language domino applications.

Advantages:

It’s fast! There are no dblookups to any other data in the database;
It’s highly structured/standardisd, allowing other developers to easily read your code;
All translations are stored centrally in the design. Adding a new language and chaging current ones is relatively easy, since you know where to look.

Disadvantages:

Reading the form in designer mode is a bit more difficult;
Translations are embedded in the design of the application. If you need a front-end to add/change languages, you will have to modifiy the described method.

Editor's Note:

Thanks to Erwin van Hunen and Mark Leusink for this artlce. It's not a problem I've come across before and so I would not have though of writing it myself. Lucky for you lot that they did.

I've added an online version here for you to play with. Enjoy.

Jake, codestore.net webmaster.