© 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
Lotus Globalization Center
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
3
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
5
Difficulties in Notes template globalization (cont.)
Notes application
Script
Folder
ViewFormul
a
Notes application
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
6
Difficulties in Notes template globalization (cont.)
Tagging
Tag
Term
Tagged application
Glossary (for translation)
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
7
Difficulties in Notes template globalization (cont.)
Building
Build
Translation
Tagged application
Translated glossary
Language application
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
8
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
10
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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)
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
16
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
20
Avoid using concatenation strings in your codes (cont.)
Figure4.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
21
Avoid using concatenation strings in your codes (cont.)
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
22
Avoid using concatenation strings in your codes (cont.)
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
23
Avoid using concatenation strings in your codes (cont.)
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)
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
25
Do not use translatable strings as programming conditions
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
26
Do not use translatable strings as programming conditions
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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")
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
36
Create the alias for the keyword of option field (e.g. Listbox, Checkbox, etc)
Figure7. Listbox choices list
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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)
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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=")
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
40
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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%
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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.
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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
Lotus Globalization Center
Best practice to develop a good Notes application from the globalization perspective © 2010 IBM Corporation
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