Best practice to develop a good notes application from the globalization perspective

© 2010 IBM Corporation

Lotus Globalization Center

1

Best practice to develop a good Notes application from the globalization perspective

Xiao Feng Ji: [email protected] Ling Xu: [email protected]

IBM Lotus Notes/Domino Globalization Team


Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation

2

Agenda

Difficulties in Notes template globalization (versus general application) Brief on Domino Global Workbench (DGW) Notes template globalization process How to avoid the improper code/design from globalization perspective International Considerations



3

Agenda




4

Difficulties in Notes template globalization

Single Source Single Executable for general application

Base Product

en

pt-BR

dezh-TW

fr es ja

it zh ko

... xx

Language Packs

zh-TW



5

Difficulties in Notes template globalization (cont.)

Notes application

Script

Folder

ViewFormul

a

Notes application



6


Tagging

Tag

Term

Tagged application

Glossary (for translation)



7


Building

Build

Translation

Tagged application

Translated glossary

Language application



8

Agenda




9

Domino Global Workbench

Domino Global Workbench (DGW) is a Domino Designer application which allows to localize the design of Domino applications as well as manage the translation workflow of their documents. It therefore enables Web application developers to quickly and cost-effectively deliver multilingual Web and intranet applications.



10

Agenda




11

Process for localizing the design of a source application

Checking and fixing the design of the application, so that it is truly international.(Notes)

Extracting the strings of the application to be localized in a DGW translation glossary(DGW)

Preparation of the DGW glossary and simulation of translation with pseudo-translation.(Notes)

Translation of the DGW glossary. (Notes) Intermediate building (DGW) Reviewing/Adjusting translations according to the intermediate

building (Notes) Updating (DGW) Preparing the updates, translating the updates (Notes) Building (DGW) Reviewing/adjusting translations of the updates (Notes) Fixing the layout and other post-building tasks (Notes)



12

Creating a DGW project for the application to be localized

DGW Projects hold the settings for the localization of Notes applications.

For each application to be localized, the project will contain the following items with their settings.

Source application This is the application to be localized. It can be a database (.nsf) or a template (.ntf). It can hold Notes Design elements, as well as user documents (called Help documents) and the Notes Profile document.

Glossary database The glossary database (.nsf) will holds the strings which DGW extracts from the Source application. It is created with a specially design template which has been installed during the DGW installation. (It is also possible to use customized DGW glossary templates.) The glossary database will hold the translations.

Tagged application The tagged application is the logical link between the translations and the source application. It is automatically created when DGW performs the extraction of strings into the glossary. It also holds information for later updating.

Language application

This is the localized application, and results from building the source, the tagged applications and the glossary databases



13

Populating the glossary

Once the glossary has been created and set up, the next step consists in populating it with the strings to be localized. DGW extracts the strings from the source application and creates entries for them in the glossary (this is where translation will happen).

In order to be able to build the translations at a later stage, DGW needs to write "markers" everywhere it has extracted strings from the source application.



14

Preventing strings from being translated (DNT)

At extraction time, DGW cannot differentiate between translatable strings and functional strings. Therefore, the glossary database contains many functional strings which must not be translated.

In addition to this, Notes application design contains a certain volume of strings which do not need to be translated as they are mainly there for the developers or the localizers information.



15

Overview of the building process

At build time, DGW takes a copy of the tagged database and replaces the tags with the relevant language entries from the glossary



16

Agenda




17

How to avoid the improper design from G10N perspective

Following of real cases summarized from years of Notes globalization practice, and most of these cases are easily ignored during the Notes application developing process. By following these recommended best practices, developer could design and implement a good Notes application from the globalization perspective, which in turn will save lots of effort. In addition to that, this article describes what we believe to be an effective approach to avoid these issues based on our experiences.



18

Avoid using concatenation strings in your codes

The concatenation strings will be tagged into different terms in property files or glossary database. It’s extremely difficult to make sure these terms will be combined correctly after translation.

In short, if the translated text is constructed just by concatenating the strings, the constructed sentences may no longer be grammatically correct in other languages. The following Listing 1 shows an example :

@If(FirstDayOut = "" | FirstDayBack = ""; ""; "I will be out of the office starting " + @Text(@Date(FirstDayOut)) + " and will not return until " + @Text(@Date(FirstDayBack)) + ".")

Listing 1. Code piece for using concatenation strings in Formula



19

Avoid using concatenation strings in your codes

The full sentence won’t be tagged into the one term in the property file if it contains the concatenation strings. Instead, they will be tagged into separate terms without context. Listing 2 shows how the resourced out properties look like. Figure3 and Figure4 tell you that the VAR2 and VAR4 won’t be resourced out.

Figure3.



20

Avoid using concatenation strings in your codes (cont.)

Figure4.



21


In Listing 2, the structure of Properties files is relatively simple: typically everything that follows an equal sign needs to be translated; everything that is preceded by a hash mark (#) is to be excluded.

So when these separated strings are sent out to translator and translated into another language, the translator is not able to know whether they will be shown as one sentence on the UI. These separated terms will be translated without context, and lead to obscurity or even misunderstanding. Sometimes the concatenation strings have different combinations in different languages. The verb used in this string may not be used in another string due to language culture difference. The sentence order needs to be adjusted after translation.

Form.(Out_Of_Office_Profile).Str1=I will be out of the office startingForm.(Out_Of_Office_Profile).Str2=and will not return until

Listing 2. Resourced out translatable terms



22


Listing 3 depicts the proposed approach to avoid the concatenation in your code. That’s one of the solutions.

@ReplaceSubstring("I will be out of the office starting var_startdate and will not return until var_returndate.";"var_startdate":"var_returndate":@Text(@Date(FirstDayOut)):@Text(@Date(FirstDayBack)))

Listing 3. The proposed approach to avoid using concatenation strings

@If(FirstDayOut = "" | FirstDayBack = ""; ""; "I will be out of the office starting " + @Text(@Date(FirstDayOut)) + " and will not return until " + @Text(@Date(FirstDayBack)) + ".")

Listing 1. Code piece for using concatenation strings in Formula



23


In Listing 4, the pervious separated strings have been resourced out as a whole sentence which would be much easier for the translator to understand and translate.

Form.(Out_Of_Office_Profile)_|_OutOfOfficeProfile.PostRecalc.Str1 = I will be out of the office starting var_startdate and will not return until var_returndate

Listing 4. Resourced out translatable terms(Correct example)



24

Do not use translatable strings as programming conditions

1. REM "Begin Do Not Translate"2. Const DSPIND = "dspIndividualAccess"3. REM "End Do Not Translate"

4. REM "Begin Translatable Text”5. Const CALENDER_NOTICES = "Calendar notices are automatically forwarded to this person"6. REM "End Translatable Text”

7. Set item = note.getfirstitem(DSPIND)8. strIndividualAccess = item.Text9. lposition = Instr( strIndividualAccess, CALENDER_NOTICES)10. If lposition > 0 And lposition <> 1 Then11. ' strip off fwd msg12. strIndividualAccess = Left( strIndividualAccess, lposition-2 )13. Elseif lposition = 1 Then 14. strIndividualAccess = ""15. Else16. strIndividualAccess = Left( strindividualAccess, Len(strindividualAccess)-1)17. End If

Listing 5. Code pieces for using translatable strings as programming conditions



25


In Listing 5, the program judge whether "dspIndividualAccess" is the substring of "Calendar notices are automatically forwarded to this person". Two separated properties will be created via DGW. It’s hard to make sure that the first sentence will always be translated as a sub-sentence of the second one if you are preparing to translate them into different languages. Listing 6 shows an example when translating them into Simplified Chinese, the first sentence is not the sub-sentence of the second one.

English Form.(Calendar_Profile).var1=Calendar notices are automatically forward to this person.Form.(Calendar_Profile).var2=Calendar notices are automatically forward to this person when I am a meeting chair.

Chinese Form.(Calendar_Profile).var1= 自動發送日曆通知給這個人。Form.(Calendar_Profile).var2= 當我是會議主持人時自動發送日曆通知給這個人。

Listing6. translation of two variables



26


LotusScript @Formula

Covert Cstr, Cint, Cdat, Abstract, StrConv, Lcase, Ucase,

@LowerCase, @ProperCase, @LwerCase, @UpperCase, @TextToNumber, @TextToTime, @Explode, @Replace

Compare StrToken, StrCompare, Split, like @ReplaceSubstring, @Matches@Like, @Contains

Length Mid, Len, LenC @Length

Position Left, StrLeft, StrLeftback, Right, StrRight, StrRightback, Instr, Trim, Contains, RightBP, MidBP

@Left, @Middle, @Middleback, @Begins, @Ends, @LeftBack, @RightBack, @Right

Other Join @Word

Listing 7. These functions in LotusScript and Formula should avoid to be used for translatable strings



27

Avoid using combination of text and fields on UI

Field is often used in Notes for display (e.g. Text Field), however, the incorrect use of these field will lead to globalization problems. To mix text and field is also a concatenation issue, which might be similar to what we decrypted in #1.

Form.Response.Str1=The response is forForm.Response.Str2=and was send by

Listing 8. translation of two variables

Figure5. A bad UI example



28

Avoid using combination of text and fields on UI (cont.)

As shown in Listing 9, when trying to translate this sentence into Simplified Chinese, we found that the sentence structure are different compared to the English version, so the order of the Fields may need to be changed.

English This response is for dPrincipal and was sent by dForm_1.

Chinese 這封回信是給 dPrincipal 而且是由 dForm_1 所寄送的。

Listing 9. Translate the whole sentence into Simplified Chinese



29

Add comments for DNT variables and Hidden variables

Hidden variables usually don’t need to be translated. It’s a good habit to add comments to them, because it could avoid them being translated accidentally. Listing 10 shows some good examples to add comments for the DNT variables.

1. DNT Variables in the FormulaREM "Begin Do Not Translate"<Formula Code>REM "End Do Not Translate"

2. DNT Variables in the LotusScript'Begin Do Not TranslateREM {Begin Do Not Translate};<LotusScript Code>'End Do Not TranslateREM {End Do Not Translate};

3. Always hidden variables'Begin Always Hidden variables<Hidden variables>'End Always Hidden variables

Listing 10. Add comments for DNT variables and Hidden variables



30

Add comments for translatable variables

Listing 11 shows an example to add comments for translatable variables. In Listing 11, the string order could be determined by the translator. Remember, these comments are very useful for the translator to get to know what they are translating, because most of the time, they could not see and understand the source code.

{ REM The text of the next string determines the order of display of the following strings "FamilyName" and "GivenName" }

OrderOfStings := "FamilyNameFirst";Field1 := "FamilyName";Field2 := "GivenName";

{ REM Begin DNT }FIELD Display:=@If(OrderOfStrings = "FamilyNameFirst " ;Field1+Field2; Field2+Field1){ REM End DNT }

DGW will produce property file values that will look like this.# The text of the next string determines the order of display of the following strings "FamilyName" and "GivenName"Form.Memo.Action_Label_Formula.FamilyNameFirst = FamilyNameFirstForm.Memo.Action_Label_Formula.FamilyName = FamilyNameForm.Memo.Action_Label_Formula.GivenName = GivenName

Listing 11. Add comments for translatable variables



31

Tips: Naming the DNT variable

Tips: Naming the DNT variable with a combination of uppercase and lowercase would help the translator to ignore them when translating. Listing 12 shows an example, for DNT values, naming them as as “upDatE”

REM {Begin Do Not Translate};update = "upDatE";updateInformation = "inForMation upDatE";requestInformation = "reQuesT InforMation";requestupDate= "reQuesT upDate";REM {End Do Not Translate};

Listing 12. Naming the DNT variables with a combination of uppercase and lowercase



32

Never “hard code” strings in your code

In Listing13, the translatable strings are all “hard coded”. It’s a bad example which will make the code difficult to read, understand and maintain, and also difficult for DGW to resource out. The good way is to define the strings as variables in your code(refer to Listing 13).

Function GetString(nIndex As Integer, vData As Variant) As String Select Case nIndex Case RECALL_STRING_MSGTO GetString = "Message to: " Case RECALL_STRING_MSGSTATUS GetString = " Message status: " Case RECALL_STRING_FAILREASON GetString = " Recall failure reason: " Case RECALL_STRING_NORESPONSES GetString = "Your recall request has been initiated. For more information, open the Recall Status report for this message when you receive it." Case RECALL_STRING_OTHERREPORT GetString = "Other delivery reports. (No recall information is available) " End SelectEnd Function

Listing 13. Hard coded strings in LotusScript should be avoid, below is a bad example



33

Never “hard code” strings in your code (cont.)

Function GetString(nIndex As Integer, vData As Variant) As String REM "Begin Translatable Text” Const xxMessage = "Message to: " Const xxMessageStatus = " Message status: " Const xxMessageFailReason = " Recall failure reason: " Const xxMessageInitia= "Your recall request has been initiated. For more information, open the Recall Status report for this message when you receive it." Const xxMessageOtherReport = "Other delivery reports. (No recall information is available) " REM "End Translatable Text”

Select Case nIndex Case RECALL_STRING_MSGTO GetString = xxMessage Case RECALL_STRING_MSGSTATUS GetString = xxMessageStatus Case RECALL_STRING_FAILREASON GetString = xxMessageFailReason Case RECALL_STRING_NORESPONSES GetString = xxMessageInitia Case RECALL_STRING_OTHERREPORT GetString = xxMessageOtherReport End SelectEnd Function

Listing 14. A good example to define the variables instead of hard code the strings in codes



34

Define and assign your variables ONLY at the beginning of your script

Variables should be defined at the beginning of the script, and doing this could best separate your resource with the code. In Listing 15, all the translatable and non-translatable strings have been defined at the beginning of the scripts which will make the script easy to read.



35

Do not use normal legible words when naming internal variables.

When naming internal variables, you’d better avoid using the normal legible words, instead, it’s recommended to remove the space between two words, and then the translator could understand this kind of words are non-translatable variables. Listing 16 shows an example. It’s suggested to use “InterestProfile” instead of “Interest Profile” for the document name variable.

@if(xxdocname = "Interest Profile";"Interest Profile";"Standard Document")

Listing 16. Don’t use normal legible words when naming your internal variables

@if(xxdocname = "InterestProfile";"Interest Profile";"Standard Document")



36

Create the alias for the keyword of option field (e.g. Listbox, Checkbox, etc)

Figure7. Listbox choices list



37

At least assign one alias name for the forms and views.

The form name and view name usually need to be translated because they are visible, so adding the alias name is necessary for programming consideration.

Moreover, we suggest the alias do not include space, especially if it might be used on web. Remember, the alias name is not translatable in Notes application. Please don’t assign the same alias name for the different design element.



38

Use table instead of “tab” key to separate the static text from the field.

Using “tab” key for layout control should be avoided. In Figure 8, the programmer is using tab key to align the Fields. The layout looks good in English, but after translation, they won’t be aligned, because different terms may not be translated to the same length. In Figure9, the layout becomes bad after translating into Korea.

Figure8. Using tab key for layout control(English)

Figure9. Using tab key for layout control(Korea)



39

Decode and encode the variable which will show on web

For the variables that will show on web directly, please don’t forget to encode and decode them. In Figure10 below, the window title has been HTML encoded, but not decoded, so the %XX garbage code will show on title. Listing 18 shows how to decode a variable.

Figure10. Garbage code on window title

Listing 18. Decode the variable

PartialName := @Right(@URLDecode("Domino";Query_String);"&Title=")



40

Agenda




41

International Considerations

CultureBe careful not to offend your customers. References that are not considered offensive in your country may be so in other countries. Your users are likely to be scattered across the world, belonging to many religions and races, and holding many different beliefs.Examples that make good sense in one country may not be understood at all in another. An example involving a knowledge of baseball or cricket would not make sense to many people.

ColorsAvoid bright colors, especially be careful when using red, purple, yellow and other 'hot' colors. These tend to mean different things in different cultures (for example, in the US red often signifies 'stop'). Black boxes around people's names are not acceptable in some cultures.

Icons



42

International considerations (Cont’d)

ExpansionYou are likely to encounter expansion problems if your working language (the language in which your application is developed) is one of the 'shorter' languages, such as English. Translated text can be up to 30% longer than English (more, if the text is just a word or two), so if you are working in English try to leave space for expansion when you design forms, views and so on.

Number of characters Additional space required

1 - 10 100% - 200%

11 - 20 80% - 100%

21 - 30 60% - 80%

31 - 50 40% - 60%

51 - 70 31% - 40%

Over 70 30%



43

International considerations (Cont’d)

Keep the keywords simpleIf you use keyword fields (Dialog list, Checkbox, Radio button, Listbox and Combobox field types), try to keep the keywords simple.

Writing for an international audienceWrite user interface information with an international audience in mind (for ease of translation into other languages, and for ease of understanding by non-English audiences).

Create pseudo build to foresee problemUsing the pseudo translate function in DGW Glossary template, then build the target template as usual. Test and fix source template for the defects found in pseudo-translated template before send for translation.



44

Conclusion

In this session, the background and process of Notes application Globalization has been introduced, as well as related Globalization tool DGW. The globalization of Notes application is done by extracting the translatable strings via DGW and rebuilding the translated strings into original Notes application.

We share the experience which we have gained from years of application of Notes globalization and summarize the best practices to develop Globalization Notes Application. If follow these best practices to develop globalized notes application, you would avoid problems in the design and develop stage and significantly save time and resources in the later software globalization stage.



45

References

"e-business Globalization Solution Design Guide: Getting Started", by Bei Shu, offers a comprehensive overview of globalization technologies and demonstrates how to realize cost-effective globalization.

Globalize your On Demand Business http://www-306.ibm.com/software/globalization/globprocess/index.jsp



46

T hank Y ou

M er c iGrazie

G racias

O br igado

D an k e

Japanese

English

French

R ussian

G erm an

Ita lian

Spanish

Brazilian PortugueseArabic

Trad itiona l C h inese

S im p lified C h inese

H ind i

Tam il

Tha i

Korean

T hank Y ou

M er c iGrazie

G racias

O br igado

D an k e

Japanese

English

French

R ussian

G erm an

Ita lian

Spanish

Brazilian PortugueseArabic

Trad itiona l C h inese

S im p lified C h inese

H ind i

Tam il

Tha i

Korean

Best practice to develop a good notes application from the globalization perspective

Business

Transcript of Best practice to develop a good notes application from the globalization perspective