3.5 Application localization 

Previous | Next

The explosion of the internet has ushered in a new era of business – one without borders on a multinational global scale.    To accommodate the need to communicate effectively across language barriers, Lotus Domino gives you many options to take a native-language application (such as English) and translate it into multiple languages.   These tools include Domino Global Workbench, creating individual multilingual design elements, and XPages localization, all of which are discussed below.

Design considerations

If you wish to deploy a Domino application in multiple languages, there are many design considerations that you must undertake. These include:

• The language base that your application will support (such as English, Spanish, and French).
• The level of expertise available to perform the translation of text between languages, either in-house or through an external translation service.
• The complexity of the application.
• The development of the application using traditional or XPages-based development environments.
• The scope of the application translation – will it be the entire application that gets translated, or just certain parts?
• The frequency of updates to the translated text within your Domino application.

Important note:  Translation impacts text-based data presented to the user through  the application, and does not include the translation of programming code, menus, messages, and other items therein. 

Once you have a clear picture about the application itself, you have to deploy the method that is best suit your needs in maintaining a consistent application across multiple languages, using the tools available for Lotus Domino.

Domino Global Workbench

Domino Designer extends itself naturally through  an integrated translation tool called Domino Global Workbench.  This tool, when installed along side of Domino Designer,  gives you the facilities to translate the native application into multiple languages.

Due to the complexity of implementing a Domino Global Workbench solution, we outline the steps here and reference you to the list of items at the end of this subsection for further information.

Before you begin, it is important to understand the steps involved in managing a multilingual Domino application using Domino Global Workbench:

1. You must first setup the application (either in .NTF or .NSF format)  with  the default language that you will use to construct the initial application.
2. After the application is designed, you set up a Domino Workbench glossary based on the template DWGGLOSS.NTF that is installed with Domino Global Workbench.
3. You  then use the WorkBench to construct a database from the original application. This database, called a tagged database, is identical to the database of the original application.
4. Within the tagged database, each piece of text that you want to translate is given an unique identifier (ID), which is linked to an entry in the original application. Domino Global Workbench will attempt to create tags for all translatable parts of the source application that you define.   If there is something that it cannot create a tag for, you can manually create the tag using  the workbench.
5. You must now manually translate the tagged text into the target language using the glossary created earlier and the Notes Client.
6. Now  you have the source application, the tagged database, and the glossary, you  build language databases using these components. The language database is the physical application that the  users will access.
7. Once the language databases are created, you can apply the updates  by modifying the original application and the glossary, using Domino Global Workbench to push the changes out to the language applications.
8. In addition, you can configure the Synchronizer, a Domino server task that can apply changes to the language applications automatically.

Important note:   While Domino does allow translated items to be synchronized across multiple language applications, you are still required to have the tagged text translated from the native language into the target languages.

For more information about Domino Global Workbench, please visit:

• Domino Designer Help (search for “Global Workbench”).
• An Introduction to Domino Global Workbench 8.5, located at: http://www.lotus.com/ldd/ddwiki.nsf/dx/Introducing_of_Domino_Global_WorkBench_8.5
• Translating a Domino Application using Domino Global Workbench, located at: 
  http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.designer.domino.main.doc/H_TRANSLATING_AN_APPLICATION_USING_DOMINO_GLOBAL_WORKBENCH_STEPS.html
• Product Documentation that comes with Domino Global Workbench.

Best practices

To get the most out of Domino Global Workbench, consider the following:

• Use Domino Global Workbench to translate native Domino applications into multilingual format.
• Domino Global Workbench can translate tagged text at the document level into the target language.
• Have a technical person perform the initial analysis of the native application, gathering information on what components are to be translated.
• Have a translator performs the actual language translation of the items, based on the information provided to them.
• Store the translated information in the glossary database.   This allows you to apply existing translated information to other (new) applications without having to manually translate the information again.

Design element localization

For many Domino web development efforts, it is common to use native design elements (such as forms and pages) to build web applications, opposed to document-level application development.    These web applications tend to be more static in nature, with the frequency of changes being minimized.

Localizing design elements permits Domino to work in conjunction with the language settings in your web browser to determine which design element (in what language) that Domino will deliver to you.
 
If you plan to deploy a Domino web application that relies more on design elements than documents, you can deploy those design elements to support multiple languages in a straightforward manner, as outlined below by example.
 
Step 1:   Configure the application as multilingual.
This is accomplished through the database properties dialog box, as shown:

 
The above is establishing a baseline for your application, informing Domino that the application:

• Is multilingual.
• The default language is English.
• The default region is the United States.
• Use Unicode (Universal) sorting by default.

Step 2:  Create the default language design element. 
For the purposes of discussion, the following assumptions are made:

• You want to create a Domino web application.
• You will use Pages as the key design element in your development.
• You want to support the English and German languages.

You can start by creating a new web application with a Home page utilizing the Domino Designer page design element, for English language users, as shown:


The important thing to realize is the naming convention used above:

• The design element name is always different for each design element representing the same web page in the application.   As shown above, the name describes the page as being the Home Page in the English Language.
• The design element alias is always be the same for each design element representing the same web page in the application.   As shown above, Home represents the home page, and, will be the same across all variations of the home page in different languages. 

Based on our earlier assumptions, you need two home pages – one in English, and another in German.  Therefore, you can create the German language web page as shown below:


The results of your efforts are shown below:


Step 3:  Instruct designer to display the relative design element based on the web browser default language setting.
Now that you have two pages named Home, you must tell Domino which page to display based on the default language preferences setting in the user’s web browser.
 
You accomplish this by selecting the page in the Domino Designer, and modifying the multilingual design properties at the bottom of the screen.   For example, the Home Page English page would be set as follows:

 
 And for German:

 
Important note:   Based on the above, Domino must have some way of knowing whether you want to see the English or German version of the Home page when you access the application from a browser. 

This is accomplished using the Browser Language Preference settings (for Internet Explorer, this is done by accessing the Tools -> Internet Options menu): 


The above browser configuration is set to show the German language version of the page (if available), then the English language version.

Step 4:   Populate the design element with the correct language elements.
Now that you have the web page called Home, one designated for English, and another designated for German, you can now populate each page with its respective text, graphics, media, and so on.

Consider the following text excerpt from the Domino Designer help file: 
“The Home Page is a great place to start. This page, which was previously called the Welcome Page, gives you immediate access to your mail, contacts, calendar, and more. And you can create new Home Pages, customized to suit your needs."

To make this available to German users, you must translate the text into the German language, resulting in:
"Das Home Page ist ein großer Platz, zum zu beginnen. Diese Seite, die vorher die willkommene Seite genannt wurde, gibt Ihnen sofortig Zugang zu Ihrer Post, zu Kontakten, zu Kalender und zu mehr. Und Sie können die neuen Home Page verursachen, besonders angefertigt, um Ihren Notwendigkeiten zu entsprechen.”

 You copy the respective text onto the correct page, as shown:



If you preview the Home page in browsers set to different default languages, you see something similar to the following:

You have accomplished the desired goal – to create a design element-based web application using Domino.

Best practices

When using design element-based multilingual web applications in Domino, consider the following:

• Use design elements for content that is not stored in documents.
• Use design element internationalization when the content changes infrequently.
• When using design elements, note that the web page that a user will see is based on their default browser language preferences.

Localization using XPages

As with traditional Domino applications, XPages provides a standards-based method for deploying multilingual XPages-based applications.  Unlike traditional design element duplication, XPages allows you to develop a single source application to be deployed in multiple languages.

In this section, we show the process for XPages localization and some best practices for implementing multilingual XPages applications.

Localization in-depth

To localize an XPages application, the high-level steps are:

1. Localization setup:  You must know the native (initial) language that the XPages application will be developed in, as well as configure the application to support multiple locales.
2. Localization translation:  Once your XPages application is developed, you have to export your native language interpretation and forward them to a professional translator for translation into the additional languages that your application will support.
3. Localization implementation:  Once you receive your translated information, you import the results into your XPages application.

Here we discuss these high-level steps in detail by creating an example application using the Domino Designer. You also can use Lotus Notes to create an application.  Once complete, open the new application in Domino Designer and create the following sample XPage:


Use these steps to apply the localization to this sample application or your application.

Step 1: Localization setup
You must first configure the application to support multiple languages by enabling localization, as shown in the following diagram:


From Domino Designer, perform these steps:

1. Right-click the application. Select Application -> Properties.
2. Select the XPages tab from the tabs along the bottom of the XPage.
3. Scroll down to enable localization.
4. When done, save your changes.
5. From the Project menu, select the Clean option, then, either manually build the project, or automatically build the project.

When you enable localization, you must specify the source language (the language that the application will be developed in), as well as any additional languages you wish to support (in this example, German).

When you save and close your application, localization is enabled.

Note:  The terminology used in the “Localization Options” of the XPages properties  differ slightly for applications developed using Domino Designer 8.5.0.

Step 2:  Localization translation
Once the application is developed, you are ready to export the localization information to be translated.   This is accomplished as follows:

1. Display the navigator in Domino Designer:
   If the navigator is not present in Domino Designer, you must display it using the From Domino Designer by selecting Window -> Show Eclipse Views -> Navigator
   
   
   Once complete, your Designer interface should appear similar to the following diagram:
   
2. Export the information to be translated:
   To physically export the information to be sent for translation, select the following from the navigator:
1. Right-click the application root.
2. Select Export from the menu.
   
3. The Export dialog box is presented as shown below. In this panel, select General, then File System. Click Next.  
   
4. In the File system panel (see the figure below), tell Domino Designer which components you want to export by:
• Clearing the checkmark beside the application root.
• Selecting Resources, then Files.
• Selecting XPages.
• Check the .properties files on the right side of the dialog box.
• Specify a path where the files will be exported to
  
  
3. When you click Finish, the files are placed in the directory you specified in a folder called XPages.

For this example, the following XPages properties file represents the xpSample.xsp file from the dialog box above.

Note that this is a simple text file.   This simplifies the translation process because the person performing the translation does not require access to Lotus Notes, nor to your environment. 

Also note that a reference to each piece of static text on your sample form is presented in a standard format.    This “tagged” file is used by Domino for XPage language translation, and is what you should give to the person performing the translation, who will:

• Open the xpSample_de.properties file.   This file will represent the German language version of the properties file.
• Change the text to the right of the = equal sign from its native English to the native German language.
• Save and close the properties file.
• Return it to you for importing into your XPages application.

For your sample application, the translated properties file (xpSample_ge.properties) should appear similar to the following:

The translator saves this file, returning it to you for integration into your XPages application.

Step 3: Localization implementation 
Now that you have your translated properties file, import it back into XPages, as follows:


Before you import your translated property files, prepare the XPages application not to automatically overwrite the translated property files.  This prevents changes to an application from overwriting your translated property files until you are ready to begin the export-translate-import process again.   Perform the following steps to accomplish this:

1. From Domino Designer, right-click the application.
2. Choose Application -> Properties.
3. Select the XPages tab at the bottom of the XPage.
4. Clear the check box “Merge source file changes into property files”.
5. Save your changes.
6. From the Project menu, select Clean...

To import the translated property files, perform the following functions in Domino Designer:

1. Using the application explorer, expand the application.
2. Expand XPages.
3. Right-click the properties file you want to import.
4. Select Import.
5. From the dialog box, expand General.
6. Select File System.

The results are shown in the following diagram:


After selecting Next, use the Browse button to locate the translated property files on your computer.   You must also instruct the import wizard to:

• Import the relevant translated property files.
• Create the folders within the application to hold these files.
• When importing is complete, use the Clean option from the Project menu to assure proper integration of the imported data.

The results are shown in the following diagram:

When you select Finish and confirm the operation, Domino Designer integrates the translated language files into your application.   You now have a complete, multilingual application that functions as follows:

• You access your application through a web browser.
• The Domino server detects the default language of the browser you are using.
• If the application has the relevant localized properties files, the application is displayed in that language.
• If the application does not have the relevant localized properties files, the application is displayed in the default language.

Your results should be similar to the following:

Best practices

When developing localized applications, consider the following:

• If you are using traditional Domino applications based on the document model, use Domino Global Workbench. 
• If you are localizing traditional Domino applications based on the design element model, use design element localization.
• For new and modern Domino applications utilizing XPages, use the XPages localization method.   The benefits you  receive in XPages localization over other methods include:
• XPages localization is easier to implement than Domino Global Workbench.
• Xpages localization is more flexible than design element localization, for you only have one XPage to modify.
• XPage localization allows translation to be done easily using  a text file that is exported from, and imported into, your XPages application.   This eliminates the need for Notes or Domino Designer during the translation process.
• XPages localization is more flexible than other methods, especially when adding additional languages to an existing application.
• When using XPages localization, you should follow these guidelines as a best practice:
• Make a backup of all properties files – before and after the translation.
• Clean the application after every export and import to assure that XPages properly integrates your localization changes.
• Clear the checkbox “Merge source file changes into property files” on the application properties to prevent simple changes from adversely impacting your translated files.

Parent topic: 3.0 Infrastructure impact for application development