• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Best practice to develop a good notes application from the globalization perspective
 

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

on

  • 2,196 views

This presentation shows the best practice to develop a good Notes application from the globalization perspective

This presentation shows the best practice to develop a good Notes application from the globalization perspective

Statistics

Views

Total Views
2,196
Views on SlideShare
1,655
Embed Views
541

Actions

Likes
1
Downloads
37
Comments
0

3 Embeds 541

http://www-10.lotus.com 536
http://wiki1.swg.usma.ibm.com 4
http://webcache.googleusercontent.com 1

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

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

    • Best practice to develop a good Notes application from the globalization perspective Xiao Feng Ji: [email_address] Ya Ling Xu: [email_address] IBM Lotus Notes/Domino Globalization Team
    • 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
    • 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
    • Difficulties in Notes template globalization
      • Single Source Single Executable for general application
      pt-BR de zh-TW fr es ja it zh ko ... xx Language Packs zh-TW Base Product en
    • Difficulties in Notes template globalization (cont.)
      • Notes application
      Script Folder View Formula Notes application
    • Difficulties in Notes template globalization (cont.)
      • Tagging
      Tag Term Tagged application Glossary (for translation)
    • Difficulties in Notes template globalization (cont.)
      • Building
      Build Translation Tagged application Translated glossary Language application
    • 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
    • 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.
    • 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
    • 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)
    • 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
    • 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.
    • 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.
    • 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
    • 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
    • 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.
    • 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 :
      Listing 1. Code piece for using concatenation strings in Formula @If(FirstDayOut = "" | FirstDayBack = ""; ""; "I will be out of the office starting " + @Text(@Date(FirstDayOut)) + " and will not return until " + @Text(@Date(FirstDayBack)) + ".")
    • 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.
    • Avoid using concatenation strings in your codes (cont.) Figure4.
    • 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.
      Listing 2. Resourced out translatable terms Form.(Out_Of_Office_Profile).Str1=I will be out of the office starting Form.(Out_Of_Office_Profile).Str2=and will not return until
    • 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.
      Listing 3. The proposed approach to avoid using concatenation strings Listing 1. Code piece for using concatenation strings in Formula @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))) @If(FirstDayOut = "" | FirstDayBack = ""; ""; "I will be out of the office starting " + @Text(@Date(FirstDayOut)) + " and will not return until " + @Text(@Date(FirstDayBack)) + ".")
    • 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.
      Listing 4. Resourced out translatable terms(Correct example) 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
    • Do not use translatable strings as programming conditions Listing 5. Code pieces for using translatable strings as programming conditions 1. REM &quot;Begin Do Not Translate&quot; 2. Const DSPIND = &quot;dspIndividualAccess&quot; 3. REM &quot;End Do Not Translate&quot; 4. REM &quot;Begin Translatable Text” 5. Const CALENDER_NOTICES = &quot;Calendar notices are automatically forwarded to this person&quot; 6. REM &quot;End Translatable Text” 7. Set item = note.getfirstitem(DSPIND) 8. strIndividualAccess = item.Text 9. lposition = Instr( strIndividualAccess, CALENDER_NOTICES) 10. If lposition > 0 And lposition <> 1 Then 11. ' strip off fwd msg 12. strIndividualAccess = Left( strIndividualAccess, lposition-2 ) 13. Elseif lposition = 1 Then 14. strIndividualAccess = &quot;&quot; 15. Else 16. strIndividualAccess = Left( strindividualAccess, Len(strindividualAccess)-1) 17. End If
    • Do not use translatable strings as programming conditions
      • In Listing 5, the program judge whether &quot;dspIndividualAccess&quot; is the substring of &quot;Calendar notices are automatically forwarded to this person&quot;. 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.
      Listing6. translation of two variables 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= 當我是會議主持人時自動發送日曆通知給這個人。
    • Do not use translatable strings as programming conditions Listing 7. These functions in LotusScript and Formula should avoid to be used for translatable strings 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
    • 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.
      Listing 8. translation of two variables Figure5. A bad UI example Form.Response.Str1=The response is for Form.Response.Str2=and was send by
    • 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.
      Listing 9. Translate the whole sentence into Simplified Chinese English This response is for dPrincipal and was sent by dForm_1 . Chinese 這封回信是給 dPrincipal 而且是由 dForm_1 所寄送的。
    • 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.
      Listing 10. Add comments for DNT variables and Hidden variables 1. DNT Variables in the Formula REM &quot;Begin Do Not Translate&quot; <Formula Code> REM &quot;End Do Not Translate&quot; 2. DNT Variables in the LotusScript 'Begin Do Not Translate REM {Begin Do Not Translate}; <LotusScript Code> 'End Do Not Translate REM {End Do Not Translate}; 3. Always hidden variables 'Begin Always Hidden variables <Hidden variables> 'End Always Hidden variables
    • 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.
      Listing 11. Add comments for translatable variables { REM The text of the next string determines the order of display of the following strings &quot;FamilyName&quot; and &quot;GivenName&quot; } OrderOfStings := &quot;FamilyNameFirst&quot;; Field1 := &quot;FamilyName&quot;; Field2 := &quot;GivenName&quot;; { REM Begin DNT } FIELD Display:=@If(OrderOfStrings = &quot;FamilyNameFirst &quot; ;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 &quot;FamilyName&quot; and &quot;GivenName&quot; Form.Memo.Action_Label_Formula.FamilyNameFirst = FamilyNameFirst Form.Memo.Action_Label_Formula.FamilyName = FamilyName Form.Memo.Action_Label_Formula.GivenName = GivenName
    • 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”
      Listing 12. Naming the DNT variables with a combination of uppercase and lowercase REM {Begin Do Not Translate}; update = &quot;upDatE&quot;; updateInformation = &quot;inForMation upDatE&quot;; requestInformation = &quot;reQuesT InforMation&quot;; requestupDate= &quot;reQuesT upDate&quot;; REM {End Do Not Translate};
    • 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).
      Listing 13. Hard coded strings in LotusScript should be avoid, below is a bad example Function GetString(nIndex As Integer, vData As Variant) As String Select Case nIndex Case RECALL_STRING_MSGTO GetString = &quot;Message to: &quot; Case RECALL_STRING_MSGSTATUS GetString = &quot; Message status: &quot; Case RECALL_STRING_FAILREASON GetString = &quot; Recall failure reason: &quot; Case RECALL_STRING_NORESPONSES GetString = &quot;Your recall request has been initiated. For more information, open the Recall Status report for this message when you receive it.&quot; Case RECALL_STRING_OTHERREPORT GetString = &quot;Other delivery reports. (No recall information is available) &quot; End Select End Function
    • Never “hard code” strings in your code (cont.) Listing 14. A good example to define the variables instead of hard code the strings in codes Function GetString(nIndex As Integer, vData As Variant) As String REM &quot;Begin Translatable Text” Const xxMessage = &quot;Message to: &quot; Const xxMessageStatus = &quot; Message status: &quot; Const xxMessageFailReason = &quot; Recall failure reason: &quot; Const xxMessageInitia= &quot;Your recall request has been initiated. For more information, open the Recall Status report for this message when you receive it.&quot; Const xxMessageOtherReport = &quot;Other delivery reports. (No recall information is available) &quot; REM &quot;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 Select End Function
    • 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.
    • 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.
      Listing 16. Don’t use normal legible words when naming your internal variables @if(xxdocname = &quot;Interest Profile&quot;;&quot;Interest Profile&quot;;&quot;Standard Document&quot;) @if(xxdocname = &quot;InterestProfile&quot;;&quot;Interest Profile&quot;;&quot;Standard Document&quot;)
    • Create the alias for the keyword of option field (e.g. Listbox, Checkbox, etc) Figure7. Listbox choices list
    • 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.
    • 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)
    • 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(&quot;Domino&quot;;Query_String);&quot;&Title=&quot;)
    • 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
    • International Considerations
      • Culture Be 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.
      • Colors Avoid 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
    • International considerations (Cont’d)
      • Expansion You 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%
    • International considerations (Cont’d)
      • Keep the keywords simple If you use keyword fields (Dialog list, Checkbox, Radio button, Listbox and Combobox field types), try to keep the keywords simple.
      • Writing for an international audience Write 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 problem Using 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.
    • 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.
    • References
      • &quot;e-business Globalization Solution Design Guide: Getting Started&quot;, 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