Helping customers globalize their IBM Lotus Notes applications

Globalizing IBM® Lotus® Notes® applications can be simple. IBM Lotus Domino® Global Workbench, which is released with Lotus Notes and Domino, can help customers globalize their applications quickly and easily. In version 8.5, Lotus Domino Global Workbench provides a new feature that extracts strings into properties files, thereby providing more flexibility for translation.

Share:

Tony Kuo (yjkuo@tw.ibm.com), Staff Software Engineer, IBM

Tony Kuo is a Staff Software Engineer at the IBM China Software Development Lab in Taipei, Taiwan. His areas of expertise include software globalization, globalization, and testing. He leads teams working on IBM Lotus Notes and Lotus Domino globalization and globalization verification testing. You can reach him at yjkuo@tw.ibm.com.



Pei-Yi Lin (linpy@tw.ibm.com), Staff Software Engineer, IBM

Pei-Yi Lin is a Staff Software Engineer at the IBM China Software Development Lab in Taipei, Taiwan. She is a member of the Language Engineering and Client Platform team for IBM Lotus. Since she started working at IBM in 2004, she has participated in several globalization projects for IBM Lotus Notes and IBM Lotus Domino as both an automation test engineer and a emplate developer. You can reach Pei-Yi at linpy@tw.ibm.com.



Alex Liu (liuhc@tw.ibm.com), Software Engineer, IBM

Alex Liu is a Software Engineer in the IBM China Software Development Lab in Taipei, Taiwan. He works on the globalization team for IBM Lotus Notes and Lotus. Domino Currently he leads a team performing template globalization for IBM Lotus Notes and Lotus Domino. You can reach Alex at liuhc@tw.ibm.com.



29 June 2009 (First published 24 March 2009)

Also available in Chinese Russian Spanish

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

There are lots of different definitions for globalization. As defined by IBM, globalization is the process of making applications work seamlessly, utilizing the user's preferred language and culture. Globalization is critical to the creation of a successful on-demand business. The easiest way to create a global application is to start from scratch, with a well-designed globalization architecture and good guidelines for globalization development.

Globalizing Lotus Notes applications is a challenge for a lot of customers. The code and translatable strings of Lotus Notes applications are combined by their nature. Developers usually develop a Lotus Notes application in one language and impose the translation directly on the strings using the Lotus Domino Designer client. As a result, hundreds of design elements need to be modified, language by language, whenever an application is changed or upgraded. Handling changes, managing version control, upgrading designs, and fixing problems all require a tremendous amount of effort.

This article is the first in a two-part series on globalization.

Part 1, "Helping customers globalize their IBM Lotus Notes applications," covers these topics:

  • The globalization process for Lotus Notes applications
  • The new features in version 8.5 of Lotus Domino Global Workbench that use properties files for application globalization
  • Experiences with globalizing Lotus Notes applications and upgrading multiple language applications

Part 2, "Best practices in developing a good IBM Lotus Notes application for globalization," covers these topics:

  • Lotus Notes application development guidelines for globalization consideration
  • Globalization consideration for various controls in Lotus Notes applications

The globalization process for Lotus Notes applications

The concept of globalizing a Lotus Notes application is simple. Lotus Domino Global Workbench pulls all the translatable strings from a Lotus Notes application to a Lotus Notes database called glossary. Translators can append the translation for different languages on the English (base language) strings. Then, Lotus Domino Global Workbench builds the language application base on the translation in the glossary. After testing and fine-tuning the language application, the Lotus Notes application globalization is done. Figure 1 describes the globalization process.

Figure 1. The globalization process
The globalization process

We introduce how to globalize Lotus Notes applications and the best practice for each phase of the process in the sections that follow. We do not include step-by-step instructions, though, because they are included in the Lotus Domino Global Workbench help files.


Separate translatable strings

In the first step, you need to separate all the translatable strings from a Lotus Notes application. This process is called tagging.

A glossary database is required to store the English strings for translation. The template of the glossary database is installed with Lotus Domino Global Workbench. You can create a new glossary database from the template.

If the application is not the first release, you should use the original glossary rather than create a new one so that all previous translations can be reused in the current version. Only the new or changed strings are created in the glossary, thus saving translation effort and cost.

After the source application is tagged, all new strings are added to the glossary database. You can get a language-independent database (tagged database) that contains only the application design and the links to the strings in the glossary database. Lotus Domino Global Workbench uses the tag database to generate the language application later.

Tip: If you use an existing glossary, you can select the last option, Mark Terms during tagging, in the third panel, Lookup. Selecting this option adds a field for each term so that you can see which terms still exist in the current version of the application. After you have done the globalization process, you can delete obsolete terms.

Figure 2. The Lookup panel of the Create Tagged Database window
The Lookup panel of the Create Tagged Database window

The fifth panel, Tagging, shown in figure 3, lets you select the options that you want to tag:

  • Database title
  • Formulas
  • LotusScript®
  • JavaScript
  • HTML
  • XML
  • Links
  • Template name
  • Database class name
  • Graphics
  • Inherited design elements
  • Hidden design elements
  • Private design elements
  • Java
  • MIME
  • External LSS scripts
  • Design element comments
Figure 3. The Tagging panel of the Create Tagged Database window
The Tagging panel of the Create Tagged Database window

Click Set Settings As Default to save the settings you have selected.


Mark Do Not Translate strings

After tagging, you have added all new strings to the glossary database. Some of the strings, such as keywords (for example, form type), cannot be translated. Therefore, you need to mark those strings as not translatable; we call them Do Not Translate (DNT) strings. Marking these stings prevents them from being translated and prevents potential defects after globalization.

For example, you can find the code section shown in figure 4 in the ($InternetSites) view in the Lotus Domino Address Book application. The strings in this view should be marked as DNT in the glossary because the form name should be kept in English. Translating them in this view causes the function error.

Figure 4. The ($InternetSites) view
The ($InternetSites) view

Figure 4 shows you an example of DNT strings and a good practice of keyword expression because the strings combined without spaces between words (such as WebSite are usually keywords. You can also use a mixture of uppercase and lowercase to express a keyword. Figure 5 is captured from Mail8.ntf, the (Notice) form. Here, "update" is written as upDatE to to identify the DNT strings.

Figure 5. DNT strings
DNT strings

Translation

There are a lot of English strings in the glossary database to be translated as shown in figure 6. The translation could be done in house or outsourced to an external translator. Translators need to open the glossary database, copy an English string, translate it, and store the strings in the new language to the glossary database.

Tip: Before translation, remember to run the retrieve function in the glossary database to reduce the number of untranslated strings. The retrieve function can pull the existing translation from another glossary or the glossary database itself.

Figure 6. The glossary database
The glossary database

Build language application

Now, you have a tag database and a glossary that contains the English strings and the translated strings. Lotus Domino Global Workbench creates a localized Lotus Notes application by merging the tag database and the translations in the glossary database.

Tip: Select all options for Errors/Warning Level and ensure that the Omit locale identifier option is selected in the Basics panel of the Build Options display. Do not select the Omit locale identifier option when the identifier contains country code, such as pt-BR, zh-CN, and zh-TW. The identifier creates a four-character $Language field in the localized application. Take Brazilian Portuguese, for example, which must be differentiated from Iberian Portuguese, which has an identifier of pt. See figure 7.

Figure 7. The Basics panel of the Build Options window
The Basics panel of the Build Options window

Tip: On the Options panel of the Build Options window, select these options:

  • Copy ACL from source database
  • Replace fonts
  • Preserve layout on update

These options work for the most Lotus Notes application designs. All Lotus Notes templates, such as mail8.ntf, use these options to do the globalization features.

Click Set Settings As Default to save the settings for future use.

The standard process to globalize Lotus Notes application is the steps described above. In the following section, we share additional experience to prevent globalization errors.


Store strings and translation in properties files instead of glossary databases

Before Lotus Notes and Domino 8.5, glossary databases were used to store national languages terms that were translated from English. The translation later was imported into Lotus Domino Global Workbench to build the language application. To significantly reduce human efforts in this application globalization work, beginning with Lotus Notes and Domino 8.5, properties files have replaced glossary databases as the repository of translations. This section gives you a quick picture of this radical change.

Let's look at a few major differences between glossary databases and properties files, listed here, that demonstrate why properties files are favored for translation:

  • The format. The glossary databases are in a proprietary, Lotus Notes-specific format, and they can be opened only by using the Lotus Notes client. The properties files are pure text files that can be opened with any text file editor, and they are in a standard format recognizable to most computer-assisted translation tools.
  • The contents. The glossary databases contain all the strings extractable in applications, including untranslatable strings. In the properties files, translatable strings and untranslatable strings are separated into different files.
  • The file size. Glossary databases are huge because of their database nature. Property files are much smaller because they are text files.

In the next sections, we introduce the new application globalization process in Lotus Notes and Domino 8.5, provide step-by-step instructions on how to create language applications with properties files and Lotus Domino Global Workbench 8.5, and discuss the benefits of the new process.


The new application localization process

Using the new process, you need to follow these steps to make the English applications globalized into the languages that you specify:

  1. Extract all the translatable strings from the applications to be placed in properties files and put them into their respective folders. For example, extract the properties files for the pubnames template in a folder called pubnames in a place defined in the file system. Put the properties files from the resrc8 template in the resrc folder; note that the template version number is removed here to ensure compatibility with future versions. In the properties folders, each design element has its own properties file, and the file name follows this pattern:

    Form.Switcher_Form_for_Calendar.Properties

    This file name tells you that this file contains the properties of the form Switcher Form for Calendar. The entries in this properties file adopt this format:

    type.title.subtype.subtitle.original_string=translated_string

    For example, an entry can be like this one:

    Form.Switcher_Form_for_Calendar_|_
    SwitcherForm_Calendar.Action_Label_Formula.Calendar_Archive=Calendar Archive

    From these examples, you can see that the properties file names and the entry names are all self-descriptive, thereby making it easy for translators and engineers to locate the properties files that they need.

  2. Extract and review DNT strings. Lotus Domino Global Workbench 8.5 has the ability to extract DNT strings directly from applications and put these strings into DNT properties files. When a string is in both DNT and translatable properties, Lotus Domino Global Workbench treats it as a DNT string. To prevent confusion, you need to review the strings carefully to make sure that no DNT strings are in translatable properties files and no translatable strings are in DNT files. If you need to add or remove entries in DNT properties files after you review the DNT strings, you can make necessary changes directly in the DNT properties files.

    Tip: In the transition stage from the old process to the new one, we use agents to extract the DNT strings from the glossary databases and put them into properties files, one DNT properties file per application.

  3. Translate the properties files into various languages. The translators can use common translation tools such as Trados to perform the translation work directly on these files.
  4. Build the language applications with well-translated properties files. Because properties files are much smaller than glossary databases, you can spend less time on building language applications. The savings in time and translation costs are especially evident when you build large applications, such as mail and pubnames.
  5. Adjust the layout as needed in the language applications. In some cases, the strings are truncated or extruded after they are translated into other languages. Although the layout usually does not have any effect on functionality, it can be displeasing to some users.

Benefits of using properties files

You can see these benefits in using properties files instead of glossary databases for the storage of translated items:

  • Cost savings. Because properties files are in formats acceptable by common computer-assisted translation tools, you can avoid the additional costs of developing Lotus Notes- and Lotus Domino-specific tools to maintain glossary databases. That is, users who need to access the properties files do not need to use the Lotus Notes client to work on the glossary databases, and related costs can be significantly reduced as a consequence.
  • Translation quality improvements. With the adoption of the translation-tool-friendly properties files, translators can easily know which translations were applied to a specific English term before; therefore, they can reuse appropriate translations for the term. As a result, translations for the same English term can be more consistent and can improve the overall quality of the Lotus Notes applications.
  • Language-specific prior-work retentions. Lotus Domino Global Workbench 8.5 can export and import layout properties, which means that the time-consuming layout changes made for each language version in previous releases can be retained and reused in later releases. Retention and reuse also mean that no duplicate work needs to be performed each time a newer version of the application is released.
  • DNT string management simplifications. In the new process, DNT strings are kept in separate files and do not mix with translatable strings. Therefore, translators can be sure that the entries that they see in the properties files are all pending translations, which reduces the complexity of managing terms and minimizes the chance that translators inadvertently work with strings that should not be translated.
  • Performance improvements. Because they are text files, properties files are much smaller than glossary databases. Their smaller size not only reduces the time Lotus Domino Global Workbench takes to load in translations when building applications, but also makes storing and transferring the properties files a relatively easy task.

Creating properties files and building applications with Lotus Domino Global Workbench 8.5

In this section, we show you how to create language applications with Lotus Domino Global Workbench 8.5.

Creating properties files from English applications

Follow these steps:

  1. After you start Lotus Domino Global Workbench and create a new project, select the Click Here to Choose the New Source Database to Be Localized area of the window. Then select the source English database from which you want to generate a properties file. Click Done. See figure 8.

    Figure 8. Selecting the Lotus Notes database
    Selecting the Lotus Notes database
  2. Select the Click Here to Choose the Properties Files Dir for (application name) area of the window, and select the folder in which the generated properties file is put. Click OK. See figure 9.

    Figure 9. Selecting the folder for the properties file
    Choosing the folder for the properties file
  3. Click the Create Properties button as shown in figure 10.

    Figure 10. The Create Properties button
    The Create Properties button
  4. In the window that displays, shown in figure 11, click the yellow folder button to let Lotus Domino Global Workbench know where the DNT properties file for this application is in the file system. Click OK.

    Figure 11. The Create Properties File window
    The Create Properties File window
  5. Enter your Lotus Notes password to begin the process.

    NOTE: The window that prompts for your password might not display if you have entered your password for other tasks in the same Lotus Domino Global Workbench session.)

  6. The generated properties files are put in the folder that you designated in step 2.

Building language applications

Follow these steps to build a language application:

  1. After you start Lotus Domino Global Workbench and create a new project, select the Click Here to Choose the New Source Database to Be Localized area of the window that displays, and select the English application to be localized. Click Done, and then select the source English template. Click Select. See figure 12.

    Figure 12. Selecting the English application
    Selecting the English application
  2. Select the Click Here to Choose the Properties Files Dir for (application name) area of the window that displays, and select the folder in which the generated properties files is put. Click OK.

    Figure 13. Choosing the properties files directory
    Choosing the properties files directory
  3. Select File - Add an Existing Tagged Database.
  4. In the window that displays, click Browse, and select the English application to be localized (the application chosen in step 1) one more time. Click Done. Then, select the source English template again. Click Select. See figure 14.

    Figure 14. Selecting a tagged database
    Selecting a tagged database
  5. Click the Choose Languages button in the window that displays, and select the language to which the English application is to be translated. See figure 15.

    Figure 15. The Choose Languages window
    The Choose Languages window
  6. Click the Build Language Database button in the window that displays. A new window titled Create Language Database displays. Click the yellow folder button to enter the file name for the localized application. Click Done.

    Figure 16. The Create Language Database window
    The Create Language Database window
  7. In the Basics panel of the Create Language Database window, select the options that you prefer for errors and warning levels. Click OK.
  8. In the Options panel of the Create Language Database window, select the properties options that you prefer. Click OK.
  9. Enter your Lotus Notes password to begin the process.

    NOTE: The window that prompts for your password might not display if you have entered your password for other tasks in the same Lotus Domino Global Workbench session.)

The localized application is now ready in the folder you that designated in step 6.


Lessons learned: Preventing globalization problems

In addition to the globalization process we've discussed, we also discovered some tips that can help you prevent globalization errors.

  • Log DNT information when coding. Sometimes it is hard to judge if a string is translatable. The best practice, therefore, is to add comments in the coding stage.

    You can add comments like the following one before the DNT strings:

    REM {DO NOT TRANSLATE! THIS IS AN ALIAS};

    You can also spell the strings using mixed uppercase and lowercase letters.

    Tip: Don’t try to translate an alias name, such as a form alias or an agent alias, because these names do not require translation (they are translatable, though). Keep in mind, though that an element name, which is the name displayed in the user interface, is translatable.

  • Consider a single executable design. You should consider a single body of globally executable design for any supported language. Avoid modifying the codes in different language applications after translation.

    Bad designs can cause extra work after the application is translated. What follows is an example of this kind of problem.

    Concatenation strings, usually used to reduce the code lines and duplicated expressions, can be convenient for developers, but sometimes they can require more effort in the globalization phase.

    In the example formula shown in figure 17, an agent named (emailHelper) displays a window titled with a variable string sys+" Mail System". The string looks correct in English, but in German, the correct expression is Mail system: sys, thereby requiring extra effort to fix the new linguistic problems.

    Figure 17. The example formula
    The example formula

    A better design is to compose a complete sentence if possible and to use @Replace to replace the keyword. In this case, you could change the code as shown in listing 1.

    Listing 1. Corrected example formula
    REM {END variables to translate};
    REM {Display the helper form - results are returned to current document};
    @If(helper != ""; @DialogBox(helper; [AutoVertFit]:[AutoHorzFit]:[NoNewFields] : 
    [SizeToTable]; @Replace("sysTxt Mail System";sysTxt; sys)); "");

    The strings to be tagged become sysTxt Mail system rather than Mail system. This step is one small way to help translators provide more suitable translation.

  • Use a common layout for the localized application. A large proportion of translation problems occur in the user interface. String lengths can vary from language to language. For example, word length in German is greater than in many other languages. You might need to adjust the width or length of elements in the UI for this reason.

    Take the mail template as an example. In the English environment, the DeleteCSPref field fits well in the UI. In the German environment, though, the same field, now labeled with a longer string, can cause a truncation problem, as shown in figure 18.

    Figure 18. Truncation problem in the user interface in German
    Truncation problem in the user interface in German

    Remember to reserve some space in the design phase so that you can prevent any layout problems after translation.


Conclusion

In this article, part 1 of a two-part series on globalizing Lotus Notes applications, we outlined the globalization process for Lotus Notes applications, discussed the new features in version 8.5 of Lotus Domino Global Workbench that use properties files for application globalization, and shared the lessons that we learned with globalizing Lotus Notes applications and upgrading multiple language applications.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=377932
ArticleTitle=Helping customers globalize their IBM Lotus Notes applications
publish-date=06292009