Portrait Foundation v5.0.4 Localizing ASP.NET Applications ... · powerful inbound and outbound campaign management, and best-in-class business process integration to deliver real-time

Localizing ASP.NET Applications User Guide

Edition 11.0

17 July 2014

UK

Portrait Software

The Smith Centre

The Fairmile

Henley-on-Thames

Oxfordshire, RG9 6AB, UK

Email: [email protected]

Tel: +44 (0)1491 416778

Fax: +44 (0)1491 416601

America

Portrait Software

125 Summer Street

16th Floor

Boston, MA 02110

USA


Tel: +1 617 457 5200

Fax: +1 617 457 5299

Norway

Portrait Software

Portrait Million Handshakes AS

Maridalsveien. 87

0461 Oslo

Norway


Tel: +47 22 38 91 00

Fax: +47 23 40 94 99

P o r t r a i t F o u n d a t i o n

Loca l i z i ng ASP .NET App l i ca t ion s User Gu ide

©2014 Copyright Portrait Software International Limited

All rights reserved. This document may contain confidential and proprietary information belonging to

Portrait Software plc and/or its subsidiaries and associated companies.

Portrait Software, the Portrait Software logo, Portrait, Portrait Software's Portrait brand and Million

Handshakes are the trademarks of Portrait Software International Limited and may not be used or

exploited in any way without the prior express written authorization of Portrait Software International

Limited.

Acknowledgement of trademarks

Other product names, company names, marks, logos and symbols referenced herein may be the

trademarks or registered trademarks of their registered owners.

About Portrait Software

Portrait Software is now part of Pitney Bowes Software Inc.

Portrait Software enables organizations to engage with each of their customers as individuals, resulting

in improved customer profitability, increased retention, reduced risk, and outstanding customer

experiences. This is achieved through a suite of innovative, insight-driven applications which empower

organizations to create enduring one-to-one relationships with their customers.

Portrait Software was acquired in July 2010 by Pitney Bowes to build on the broad range of capabilities

at Pitney Bowes Software for helping organizations acquire, serve and grow their customer relationships

more effectively. The Portrait Customer Interaction Suite combines world leading customer analytics,

powerful inbound and outbound campaign management, and best-in-class business process integration

to deliver real-time customer interactions that communicate precisely the right message through the

right channel, at the right time.

Our 300 + customers include industry-leading organizations in customer-intensive sectors. They include

3, AAA, Bank of Tokyo Mitsubishi, Dell, Fiserv Bank Solutions, Lloyds Banking Group, Merrill Lynch,

Nationwide Building Society, RACQ, RAC WA, Telenor, Tesco Bank, T-Mobile, Tryg and US Bank.

Pitney Bowes Software Inc. is a division of Pitney Bowes Inc. (NYSE: PBI).

For more information please visit: http://www.pitneybowes.co.uk/software/

http://www.pb.com/software

http://www.pitneybowes.co.uk/software/

Portrait Foundation Localizing ASP.NET Applications User Guide

3 of 57

About this document

Purpose of document This document explains the steps required to localize Portrait Foundation applications into new languages. It details the tools provided by Portrait and how they can be used to extract and translate text. It also explains the extra steps required to adapt the configuration to other cultures, giving a worked example of the configuration changes made for a Japanese version of the All Applications implementation.

For Smart Client applications please refer to the to Smart Client Applications branding and localization document (Smart Client Rebranding).

Intended audience Anyone considering translation their current Portrait Foundation implementation into another language.

Related documents Software Development Kit User Guide (Foundation_SDK_User_Guide.pdf)

Enhancing ASP.NET Applications User Guide (Enhancing_NET_Applications.pdf)

Localization Add-in User Guide (Localization_Add_in.pdf)

Software release Foundation Foundation 5.0 or later.


5 of 57

Contents

1 Introduction 6

2 Portrait internationalization readiness 7

3 Translation memory 8

4 The localization process 9

5 Configuration guidelines for producing a localizable profile 10

5.1 Versioning and translation 10

5.2 Text translation process 11

5.3 jQuery plugins 24

5.4 Additional localization activities 25

5.5 Testing translated version 25

6 All Applications example 26

6.1 Configuration changes 26

6.2 Web page changes 34

6.3 Miscellaneous profile changes 38

Appendix A Web component I18N guidelines 39

A.1 Globalization 39

A.2 Internationalization 39

A.3 Localization 39

A.4 Locale 40

A.5 Practical guidelines for Web Developers 42

Appendix B Locale IDs 49


6 of 57

1 Introduction

Portrait Foundation has facilities that allow you to create applications in non-English environments. This functionality has already been proven in different locales, for example Japanese and Portuguese.

This document outlines Portrait Foundation’s features that facilitate this capability, and the localization procedures required to adapt the existing profiles for different non-English (UK) markets.

The profile localization is the process of adapting it to a new culture. This entails changing culture-dependent elements within the application to make them conform to a certain locale. Culture-dependent elements are usually text and images; however images within Portrait Foundation have been designed to give them a culture-neutral appearance, so there is no need to adapt them.

Portrait Foundation already comes with a set of internationalized Contact Centre user interface components that can be easily localized

When extending the basic functionality of the Vanilla Profile, the new components must conform to certain guidelines that are outlined in the Appendix A. This is necessary in order to utilise the extra tools supplied by Portrait for localization.


7 of 57

2 Portrait internationalization readiness

Portrait Foundation supports languages other than English. The product has inherent international design and implementation that makes the migration to non-English locales a straightforward process.

Some of the features that facilitate the localization are listed below:

Unicode support All string values are stored as Unicode, hence enabling the run-time environment to handle text regardless of which code page it originated from. Unicode usage is also used within the different channels (Web/Contact Centre).

Native data types are handled in a locale-neutral manner. The Portrait

Foundation run time handles culture-dependent data types, such as date, time and currency in a locale-neutral format, hence facilitating consistent data processing across different localized platforms.

Web components are internationalized and adapted for easy localization. The Web files have been changed to make them locale-aware, hence allowing the display and capture of data (dates/times) in an appropriate format. The localizable elements inside the Web pages have also been tagged for easy extraction and translation.

Database functionality is consistent across different localized platforms. Portrait Foundation’s database schema and stored procedures are language-neutral. The configuration can be deployed to any SQL Server database with the correct collation setting. Consumer data storage and retrieval functionality is also consistent across different localized platforms.

Special Far Eastern support Portrait Foundation incorporates special

functionality to improve user experience. For example, special Input Method Editor (IME) handling for Japanese and other Far Eastern languages (CJK).

Special support for Middle Eastern languages The presentation layout can easily be adapted to allow right to left functionality for Hebrew and Arabic .

Separation between translatable text and Portrait functionality This allows direct translation without impacting existing functionality.

Localization tools are available to facilitate easy extraction and merging of localizable text. Two tools are provided: one for extracting text from the configuration and the other for handling text inside the internationalized Web files. The tools offer a shared user interface and straightforward functionality for easy text manipulation.

Integration with third-party translation tools The translation catalogues can be translated using any third-party Computer Aided

Translation tools (CATs). Successful tests have been carried out using SDLX Translation Suite (sdlx.sdlintl.com). These tools offer a translator-friendly

environment (translation workbench) and translation memory capability that allows recycling of old translations.


8 of 57

3 Translation memory

In order to allow the reuse of old translations, it is recommended that you use a translation tool that supports translation memory. A translation memory holds all content that has ever been translated (by a human). A translator compiles a translation memory during the translation process. The translation memory memorizes segments of text (usually a phrase or sentence), which the translation memory software then ‘offers’ to the translator whenever the same or a similar string of text is encountered. The translation memory ensures consistency throughout a project and increases the efficiency of the translator.

Several versions of Portrait Foundation’s profile will be produced in English over time. It is extremely important to make sure that the effort in translating the profiles is not wasted. This is why using a translation memory is recommended, as this can reduce the cost and the time of localization dramatically.

There are several tools on the market that support translation memory functionality and can be used to translate the profile. Some of these tools are listed below.

SDLX Translation Suite (sdlx.sdlintl.com)

TRADOS (www.trados.com)

Déjà Vu (www.atril.com)

StarTransit (www.star-ag.ch)


9 of 57

4 The localization process

The process to produce a non-English version of the Contact Centre is outlined below.

1 Tools have been created to enable the extraction of text directly from the Web components and configuration. The process is straightforward and very quick. The end results of this process is a translation catalogue that can be translated by partners/clients or a translation vendor.

2 The translation glossaries produced can be translated using any third-party translation tool (for example sdlx.sdlintl.com). This gives you the benefit of being able to recycle translation using translation memories.

3 Once the translation is carried out, the catalogue is used to produce localized versions of the configuration/Web components.

4 Following steps 1 to 3, a new translated profile is produced . However, this configuration is not suitable for use in certain cultures (for example, Address format may be different and certain honorary titles (for example, Lord, Lady) may not apply outside the UK so they have to be removed).

Extract culturally-

dependent components

from the configuration/

Web (text)

Carry out the translation

process

Reintegrate translation

back into the

configuration/Web

components

Customise certain

models/configuration

items to suit cultural

needs


10 of 57

5 Configuration guidelines for producing a localizable profile

The tools provided to extract text for translation follow rigid rules to determine whether text inside the configuration is translatable or not. This is why it is crucial that certain guidelines are followed when configuring new components in order to guarantee successful text identification and localization process. Some guidelines are given below:

Never display system names in the user interface. Most of the configurable components consist of a displayable name and a system name. The system name should only be used in defining the profile logic and should never be displayed in the profile’s user interface. The display name should be used instead.

Never use display names in conditional branch nodes. As most display names will be translated during localization, using them inside conditional branch nodes in a model will render the model invalid. System names should be used instead.

Distinguish between translatable and non-translatable strings inside a model. Strings can be used when mapping a node’s input or output. These strings could be displayed as part of the profile’s user interface or be system names for other objects inside the configuration.

The extraction tool needs to identify the user interface strings in order to extract them properly. This is achieved by checking the strings inside the mapping for the presence of spaces. So, as a rule, any string in the model mapping that will be displayed as part of the profile user interface should contain a space. Note that the Web user interface will trim any spaces from strings before they are displayed.

Use reference attributes in reference data group where necessary.

Some reference data items may contain extra column definitions (attributes). The localization process will translate all the attributes of string type, hence, it is imperative to use string type attributes only if they are used as part of the profile’s user interface. If they are not part of the user interface, a reference attribute should be used instead.

5.1 Versioning and translation If regular translations of a Portrait Foundation system are required, it is important to understand the principle of versioning and translation as any translated system is effectively a versioning branch from the mainline source language system.

For example, each time a translation is performed on a Portrait Foundation system, that translated system effectively becomes a stub branch from mainline development. In this scenario, the extraction of configuration, web pages and resource keys generates an index. Further changes to the source will change this index, making the reapplication of translation impossible.

Using a translation tool that supports translation memory as part of the Portrait Foundation translation process however, does provide a mechanism for persisting additional or corrected translated items. It is possible, when using a translation tool such as SDLX, to add additional translated items to the translation memory. It is also possible to correct mistakes in translation within this translation memory. An updated translation memory allows later translations to benefit from previous work, providing the full translation process is followed each time. This is why using translation memory is the recommended process.

The following diagram serves to illustrate the versioning and translation concept:


11 of 57

Translation Process 1 Versioning & Translation

5.2 Text translation process

5.2.1 Extraction, translation and merging

Text translation forms the bulk of the localization effort. Portrait Foundation comes with tools written specifically to automate this process and make it easier.

It is important to understand that it is preferable to update the translation memory and in some cases, the mainline system to facilitate the persistence of translation updates; as manual or ad-hoc direct translation is effort that will have to be reproduced each time a translation is carried out.

5.2.2 General approach

The general approach to extracting text, translating it and merging it back is shown in the diagram below.


12 of 57

5.2.3 Updating a previously translated system

5.2.3.1 Update translation memory and retranslate or ad-hoc direct translation

Before any amendments are made to a previously translated Portrait Foundation system, it is important to decide on one of two strategies:

List break

1 Update translation memory (and/or source files) then retranslate

or

2 Ad-hoc direct translation

5.2.3.2 Update translation memory (and/or source files) then retranslate

This is the recommended process as any changes will persist for future translations, but it slower and requires repeating the translation process from step 1 so may not always be suitable.

When following this strategy it is important to consider the nature of translation errors. Errors can be categorised as follows:

Contextual errors


13 of 57

Missed terms

Translation mistakes

Contextual errors

A translated term can appear out of context for the following reasons:

Misunderstanding of source language, for example English, term context

Source language, for example English, term used in multiple contexts

Misunderstanding of source language term context

Misunderstanding of a source language, for example English, term’s context can be easily solved in subsequent translations by revisiting the translation tool (e.g. SDLX). Identify the source language term incorrectly translated and then change the translation of that term. The translation memory can then be updated to remove this error from subsequent translations.

Source language term used in multiple contexts

An example of multiple contexts for some English source language terms are shown by below:

Source (English) Context Target (German)

To Until Bis

To Destination Nach

To solve this issue, revisit the mainline source language system and redefine the source language terms that have more than one contextual meaning so that they are unique. A suitable method would be to change the terms to remove ambiguous context. When the translation process is performed subsequently, both new versions of these terms will be offered for translation.

For example, where the term ‘To’ appears in the English system, change it to be either ‘Until’ or ‘Destination’.

When terms are next extracted, the translation tool will request a translation of both ‘Until’ and ‘Destination’. The translation memory will then successfully replace the English terms with a translated term of the correct context.

Alternatively, where a term has a special context, but no obvious English word can used to describe it, prefix the word in the mainline English system with an identifier.

e.g. .Change ‘To’ to ‘C1To’ and ‘C2To’.

Again, when terms are extracted, these two new terms will be presented for translation.

Missed terms

Portrait Foundation’s translation extraction tools are designed to extract every textual item from configuration, web pages and common resources. Occasionally, an item is missed by the extraction tool. These missed items will not be translated. They should be reported to Portrait Support in order to improve the extraction software.

To solve this issue quickly, it is recommended to translate this term permanently within the mainline English system.

Translation mistakes

Spelling, punctuation or sentence case mistakes should be changed in the translation tool in a similar way to a misunderstanding of context.


14 of 57

5.2.3.3 Ad-hoc direct translation

Although this has the advantage of producing results quickly, it is not the recommended approach as any direct work on the translated system will have to be reproduced each time a translation is performed. However it can be suitable in some circumstances.

Ad-hoc direct translation is carried out directly on the workspace, web pages or common resources of the translated system. Locating errors requires a good knowledge of the construction of the system. It is suggested that ad-hoc translation is only carried out when speed of delivery overrides the desire not to repeat work.

5.2.4 Translation process steps

The actual text translation process can be broken into 8 distinct steps:

List break

1 Install Visual Studio resource key plug-in

2 Extract translatable items

3 Apply translation memory

4 Generate translated .cat file

5 Merge translated items, creating new translated version

6 Deploy and build new translated version

7 Test translated version

8 Decision:

either

a Update translation memory and retranslate

or

b Perform ad-hoc direct translation

The following diagram serves to illustrate the translation process:


15 of 57

Translation Process 2

9

The following sections describe the tools used and explain the procedures.

5.2.5 Translating hard coded strings in the database

It is necessary to translate certain reference data items held in the database directly. There are two reference data groups to consider (workflow events and


16 of 57

simplex channels), and for convenience a database script has been provided to

assist with this translation task. In order to carry out the translation

create the database as described in the Installation Guide

Load the script translate_reference_data_items.sql into SQL Query Analyzer; this script is on the CD-ROM under the folder Software\Tool\Database\Useful_scripts.

Edit the script and translate the marked text as described in the script comments.

Execute the script on the newly created database.

5.2.6 Switching Localization flag for Web files

The .NET pages are coded such that localized strings are displayed when an application flag is set. This flag is located in the web.config file in the application folders.

The flag has to be set to true prior to running the localized version of Portrait Foundation’s profile. This can be achieved by opening web.config from the application folder and changing the EnableLocalization key to True. Note that this step has to be carried out for the Portrait Application Centre, Portrait Campaigns Manager, Portrait Internet Samples and Portrait Generic Service application folders in Portrait’s implementation directory.

So the key will look as shown below

<add key="EnableLocalization" value="True" />

5.2.7 Setting the culture for the Web Application

The culture for the web application is set in the web.config file in the application folders. The attributes culture and uiCulture on the globalization element have to be set to ensure the correct translation of dates and currency values. These values contain the short name abbreviation of the Locale ID. Appropriate values are given in the table in Appendix B Locale IDs.

The text below shows the default values.

<globalization requestEncoding="utf-8" responseEncoding="utf-8" culture="en-GB" uiCulture="en-GB" />

5.2.8 Extracting text from Web files

Certain components of the Web pages, such as client side JavaScript and XSLT files have to be processed to extract the text inside them to a translation catalogue, translate the catalogue then use the catalogue to generate a new set of translated files.

List break

1 Copy the portrait_client folder from the default web root directory (default is c:\inetpub\wwwroot) to Portrait Foundation’s implementation folder (default is C:\Program Files\PST\Portrait Implementation\Systems\<system_name>\MyPortrait\Web Pages).

2 Launch the Web Page Translator from the All Programs > Portrait Foundation > Localization menu and click Add Source Files. The Browse for Folder dialog is displayed.


17 of 57

Figure 1 – Browse for Folder dialog

3 Select the Portrait Implementation folder where the Web files reside and click OK.

4 The files in the selected folder are added to a grid in the application’s main view.

5 Click the Extract button in the toolbar and specify the output translation catalogue file. This will go through all the JavaScript and XSLT files, locate all the text that has been marked as translatable, and copy it to the translation catalogue.

The output file contains the data in a delimited file format with the second column being the translatable text. The next step would be to translate this catalogue as described in 5.2.9 then merge the translation back to reproduce a translated version of the web pages.

5.2.9 Translating the catalogue

A translation tool is used to extract the text inside the produced catalogue file. This shows the text in a translation environment. At this stage, it is possible to load an existing translation memory and extract the translation from there, hence reducing the overall translation effort.

The produced Translation Catalogue is a UTF-8 delimited file consisting of two or three columns separated by a <DELIM> tag. As shown below, the first column in the file holds the original text that is usually in English. The second column should contain the translation and the third optional column contains comments and context information to aid in translation.

SOURCE TEXT<DELIM>TRANSLATION TEXT<DELIM>CONTEXT

So, translating the following line in the file:


18 of 57

This is English Text <DELIM>This is English Text <DELIM>Message

will produce:

This is English Text <DELIM>New Translation <DELIM>Message

In order to accommodate multi-line paragraphs in the translation catalogue, special tags are used in place of the normal carriage return and line feed characters. These tags are <CR> and <LF> for carriage return and line feed respectively. It is important to accommodate these tags during the translation process. For example:

Paragraph1<CR>paragraph2<DELIM>Paragraph1<CR>paragraph2<DELIM>

will become:

Paragraph1<CR>paragraph2<DELIM>Tr-Paragraph1<CR>Tr-paragraph2<DELIM>

5.2.10 Examples using SDLX to translate the catalogue List break

1 Start the Edit module within SDLX.

2 From the File menu, select New Translation. Make sure that the file type is Generic Delimited, and select the source and target language with the encoding set to Unicode (UTF-8).

Figure 2 – New Translation dialog

3 Click Options to set up the extraction setting. The settings should look as

shown in Figure 3. The settings are stored for subsequent new translations. Alternatively, they can be saved as a new schema.


19 of 57

Figure 3 – Generic Delimited Filter Options dialog

4 Once the options are set, select the translation catalogue file and click OK. To start translation, from the Translation Memory menu select Apply then click OK. This will set up the translation environment as shown below in Figure 4. If there is a translation memory from old projects, then refer to section 5.2.10.2 for information on how to recycle that old translation.

Figure 4 – SDL Edit dialog

5 Start inputting the translation and be sure to press Return for every segment that is translated (the segment colour should turn blue). Once the

translation is finished, save the file and click the preview button . This will produce a new version of the translation catalogue that contains the new translation.


20 of 57

5.2.10.1 Creating a translation memory

Once the files are translated, from the Translation memory menu select New, and create a new empty translation memory file. From the Translation memory menu select Update to save the translation segments that have been confirmed by pressing the return key. These appear in blue on the screen.

One translation memory can be used to store the translation of more than one catalogue. It is recommended that one master translation memory be used per project. Translation memory can be updated whenever the translation is changed.

5.2.10.2 Using the translation memory

Once a new translation is started from a new catalogue file. Open the old translation memory then click Apply. This will scan for segments that have already been translated, and insert them in the translation environment.

Figure 5 – SDL Edit dialog with translated material

5.2.11 Merging the translation back into Web files List break

1 Once the translation is finished, it must be merged back to produce a localized version of the Web pages. To do this, the Web files are loaded into the tool by clicking the Add Source button.

2 Click the Merge button in the toolbar. You are prompted to select a destination folder where the new translated files will reside. Make sure to point to a new folder that has been created previously.

3 The software will then prompted to select the translation catalogue. Select the catalogue that contains the translated text.

4 At this stage, a new translated version of the XSLT, HTC and Jscript files is produced. These files have to be copied over their English equivalent.

5 Copy the new translated files in Portrait_client folder back to their original location in the system’s web directory (default is c:\inetpub\wwwroot)

5.2.12 Translating the .NET resource catalogues

The Web pages are shipped with translation catalogues that are used by the .Net pages at run time. These catalogues are formatted as described in section 5.2.9 and can be translated using a third party tool, such as, SDLX as described in section 5.2.10.


21 of 57

A full set of catalogue files that need to be translated are generated by the

Foundation SDK Build Environment. For the MSI implementation install these files will be located here:

<build_env_location>\output\Repository\WebServer\WebApps\ContactCentre.Net\resources

For the Non MSI implementation install these files will be found here:

<build_env_location>\output\Release\WebServer\WebApps\ContactCentre.Net\resources

Developers can also use the Repository Extractor tool which is installed by the Foundation SDK when the “MSI Implementation Install” feature is selected. Simply run FdnRepositoryExtractor.exe from the following folder:

<sdk_install_path>\Build Environment\Template\Portrait_Projects\MSI\CommonFiles

For more details please refer to the Software Development Kit User Guide.

To simplify the translation process, all these resource catalogue files should be merged into a single CommonResources.cat file. This is achived by launching the Combine Resource Catalogue Files tool from the All Programs > Portrait Foundation > Localization menu, selecting the relevant Resources folder and catalogue files, then clicking Generate.

Once this catalogue file has been translated as described in previous sections, the translated resource catalogues have to be compiled so that the .NET applications can use them. This is carried out by launching the Resource Compiler from the All Programs > Portrait Foundation > Localization menu. The Resource Compiler will show a file selection dialog; this dialog should be used to select the translated version of commonresources.cat. Once this is done, a second file selection dialog is shown; this dialog is used to save the compiled resources. Use the dialog to save the compiled resources as commonresources.resources in the Resources folder. Note that this process has to be carried out for the resource catalogue files of every application (e.g. ContactCentre.Net and InternetChannel.Net).

5.2.13 Translating Error Catalogues

The latest version of Portrait Foundation contains an error catalogue that is utilised by all the Portrait Foundation software components. All portrait releases after 2.5 contain an error reporting framework that is responsible for capturing error messages and displaying them as part of the user interface.

The shipped version of the error catalogue is in English, however, it is possible to produce a localized version if required. This section describes the steps required to carry out the localization process.

Translating the error catalogue

The error catalogue is embedded as a resource in a runtime DLL called basemessagesU.dll which in turn is loaded by the operating system to allow message retrieval using Win32 APIs.

The project that compiles the catalogue file and creates the runtime DLL is on the CD under Software\Examples\LogMessages\BaseMessages. To translate the catalogue, load the file BaseMessages.mc in an editor (e.g. notepad or MS Word), ensure you make the file not read-only.

List break

1 Change the string LanguageNames=(English=0x409:MSG00409)

to indicate the target language in which the catalogue is being localized. English=0x409 has to be changed using values in Appendix B. For example, the Japanese equivalent should be LanguageNames=(Japanese=0x411:MSG00409)

2 Replace the word English in the document to the target language that has been specified in the previous step.


22 of 57

3 For every message in the catalogue, you can translate the parts highlighted

below; i.e. the Message and AdditionalInfo sections

MessageId=1028

Severity=Warning

Facility=TaskEngine

SymbolicName=WF_E_DATABASEUNAVAILABLE

Language=English

Message:Database unavailable%r

AdditionalInfo:%13%r

HRESULT:%12, Source:%9(%10), Facility:0x%1, Type:%2, Category:%3, Severity:%4, MachineName:%5, Process:%6, Thread:%7, Time:%11, ActivityToken:%8%r

Data is the serialised LogMessage

.

;MESSAGE_SHORT_TEXT( WF_E_DATABASEUNAVAILABLE, L"Database

unavailable" ).

4 Note that the messages contain place holders that are filled by the runtime with values. These place holders are prefixed by the percent (%) sign and it is important to keep them in the translated messages, otherwise the system may degrade in functionality. Portrait recommends keeping the AdditionalInfo string in English and translating only the Message string as this will make it easier for Portrait Support to diagnose problems.

Rebuilding the catalogue and installing it.

Once the translation process is finished, a new DLL has to be generated.

List break

1 Make sure Portrait Foundation SDK is installed.

2 Open BaseMsgs10.vcxproj using Visual Studio. This project is located on the Release CD under Software\Examples\LogMessages\BaseMessages.

3 Rebuild the solution.

4 Stop Portrait services.

5 Copy the output BaseMessagesu.dll and BaseMessagesU.pdb over the shipped dlls.

6 Restart Portrait services using Service Check.

5.2.14 Extracting text from configuration

Each configuration workspaces has certain elements that are translatable. The definition of these elements is stored in an extraction setting file that has been created specifically for the configuration. In order to make sure that the correct text is extracted, the extraction settings file has to be loaded by the Configuration Translator tool. Loading the file needs to happen once, as it will

be automatically loaded whenever the tool is launched. Loading the extraction setting file is described below:

List break

1 Select the settings file shipped with the workspace. This file which has an extension of NLSF is located in the \Software\Tools\Localization folder on the CD-ROM.

2 The NLSF file must be copied from the CD to either your Hard drive or a network share.

3 Change the properties of the file from being Read only.


23 of 57

4 Launch the Configuration Translator from the All Programs > Portrait

Foundation > Localization menu.

5 From the File menu, select Options.

6 Click Load Config. This will start a file selection dialog. Select the NLSF file you saved to your Hard drive or network share earlier. If the tool fails to extract certain elements, this is because the setting file does not have the elements’ definition. Contact Portrait Support to request an update.

7 Click OK to close the dialog.

5.2.15 Model text analysis

Not all text inside the configuration models is translatable. The supplied tool can analyse the text and allow you to determine which elements are localizable, as described below.

NB: If you do not perform this step, then no model text will be extracted for translation. This step must also be run before performing a merge.

List break

1 Before you start an analysis, you must add the files to the tool. Click Add Source Files and select the folder where the configuration workspace resides. This may take several minutes as the tool tries to load the whole workspace.

2 From the File menu, select Options. The Options dialog is displayed.

3 Click New Analysis and wait. The Model text analysis is a lengthy process and may last for several minutes. Once the analysis is finished, all the text inside the models will be shown in the dialog. You can now review the text, and check the translatable elements.

Figure 6 – Options dialog

4 Click OK to close the dialog.


24 of 57

5 Once the workspace is loaded in the tool and the preferences are set, extract

the text by clicking in the toolbar. Specify the translation catalogue file name and click Save to start extracting.

6 Translate the catalogue using a third-party translation tool. See section 5.2.10 for an example of how to translate the resource catalogues.

7 Click the Merge button in the toolbar. You are prompted to select the output folder and translation catalogue.

8 Select the output directory where the new localized workspace will reside and then you are asked to select the catalogue that contains the translated text. Once the catalogue is loaded, click OK to start merging.

5.2.16 Extra steps before deployment

The model has to be updated after translating the configuration and prior to deployment. This is because the translation process does not update references to authentication nodes inside models. The steps required to carry out this update are as follows:

Edit the model Authenticate Party and edit the node Authenticate consumer so that it points to the new translated authentication interaction.

5.3 jQuery plugins jQuery UI Datepicker

The datepicker control referenced in the Enhancing .NET Applications User Guide provides support for localizing its content to cater for different languages and date formats. The default language/date format is English (US), but the “Portrait Platform - User interface utilities” package also contains the files required to support…

[de] - German

[en-GB] - English (United Kingdom)

[es] - Spanish

[fr] - French

[ja] - Japanese

[pt-BR] - Portuguese (Brazil)

Note that the currency symbol GBP has to be translated to its equivalent currency ISO code.


25 of 57

The globalization uiCulture configuration setting in Web.config is used to

dynamically load the correct localization file. If there is no file that matches the selected language the default English (US) is used. Other files can be downloaded or manually created and included in your Portrait Foundation Implementation install. For more information on creating or downloading these files please goto http://jqueryui.com/demos/datepicker/#localization

To ensure the correct language/date format is used, the uiCulture value must exactly match the value in square brackets above.

<configuration>

<system.web>

<globalization requestEncoding="utf-8"

responseEncoding="utf-8"

culture="es-ES"

uiCulture="es" />

</system.web>

</configuration>

5.4 Additional localization activities Direct text translation is not always enough to make the Contact Centre behave in a culturally acceptable manner. For example, the Vanilla Profile comes with settings that are UK by default; for example address format, name format and reference data, such as, titles. Extra steps must be carried out on the localized configuration. These steps are as described below:

Change reference data items to make them applicable to the local market. This will include honorary titles, marital status and so on. Rather than reconfiguring the reference data from scratch, it is recommended that you modify the existing configuration. This is to make sure that models function properly.

Change currency symbols in generated and custom interactions. The

currency symbol will be extracted when the configuration is translated as described in the previous sections. It is up to the translator to change the GBP symbols (£) to their equivalent currency.

Adjust culture-dependent layouts, such as address and name format to make them conform to cultural standards. This applies mainly to generated interactions, such as address details and name entry. A Configurer should always make sure that generated interaction inputs and outputs remain the same so that models function properly

Adjust name views (in Agent/Customer) to reflect how a person should be addressed. The Vanilla Profile comes with the name composed as First Name plus Surname. This layout may not be acceptable in certain countries, for example, Surname precedes the First Name in Japan. The order in which the different name components are put together is the same as they appear in the Name View inside the configuration.

5.5 Testing translated version Each time a new translation takes place, it essential that a full regression test with a language expert takes place. Machine translation can only ever be partially successful, there will always be exceptions to the automatic translation rules. These exceptions can be spotted quickly by a local language expert.

http://jqueryui.com/demos/datepicker/#localization


26 of 57

6 All Applications example

This section gives an example of the changes that were made to the All Applications implementation that was localized to the Japanese language. This includes all changes made to the configuration data and to the Web pages (including .xslt, .htc and .js files). The main pupose of this is to highlight the sort of steps that need to be considered when localizing your Portrait Foundation application.

There are two main areas described. The first describes the changes made using the Configuration Suite to the base profile. The second section describes the changes made to the supporting Web pages.

NB: This example uses an earlier version of Portrait Foundation before the introduction of packages, overrides, overlays and user interface views. This means that some of the steps listed below are no longer possible or require a

different approach to achieve the configuration changes.

6.1 Configuration changes The main areas that needed to be modified in order to reflect Japanese specific formats are detailed in the sections below.

6.1.1 Name format and order

Requirement

The requirements for Name format is:

Surname followed by First name.

No Title or Initial fields.

Summary

Changes to configuration were made to:

Remove Title and Initial from Party views.

Change the order of the fields in the views for each party, where applicable

Remove Title and Initial from generated interactions.

Change the order of the Surname and First name fields in generated interactions.

Update models that include the generated interactions that have changed and update input and output mappings.

Update models to remove functionality relating to the capture and manipulation of the ‘Title’ and ‘Initial’ data

Update scripts that format names so that title is removed and the order is correct.

A detailed description of each of these changes is described below:

Remove Title and Initial from Party views.

The Title and Initial fields were removed from the following Party’s views. The views can be found directly under each Party definition in the tree. For example, Parties—Consumer—Views.


27 of 57

Party type Views changed

Consumer Personal details

Title and Initial were deleted from the view (Select Delete from context menu as shown below and click Yes in the confirmation message box).

Figure 7 – Remove name and title

Changes to order of fields

The following Party’s views were changed to alter the name order. The views can be found directly under each Party definition in the tree. For example, Parties—Consumer—Views.

Party type Views changed

Consumer Name view, Personal details, Search summary view

Individual Search summary view

Agent Name view, Search summary view

The order of fields is changed by selecting Order view fields from the context menu on the Name View node in the tree as shown below.

An extra step is required to change the name order in the search criteria. This step involves Web changes that are described in section 6.2.2.

Figure 8 – Order view fields


28 of 57

Use the buttons in the Order Manipulation dialog to move the items into the

correct order.

Figure 9 – Order Manipulation dialog – Name view

Removal of Title and Initial questions

There is a generated interaction that asks for the Title and the middle initial of the name to be entered. This needs to be modified as follows:

Supporting Definitions—Generated Interactions—Domains

Name (compound question domain)

To do this:

Validate which models refer to questions in the domain. This is done by right clicking on the questions and selecting the ‘Find dependants…’ option in the context menu. Make a note of the items that refer to the questions and ensure that the list corresponds with those elements identified below. It should be noted that where any other items are found in the search that the changes detailed below will have to be applied additionally.

Check out the domain and select Delete from the context menu. (This is done in the same way as deleting attributes from views as shown above.)

Change order of Surname and First name questions

There are a number of generated interactions that include questions about the Surname and First name. The order of these questions was changed. The domains that needed to be changed are:

Supporting Definitions—Generated Interactions—Domains

Domain Name GI Type Page Display Name

Name Compound question domain

Name


29 of 57

Domain Name GI Type Page Display Name

Amend or add new agent Domain New Amend Agent

Expire Agent Domain Page One

Mortgage Quote Domain Quote Summary

To do this:

Check out the Domains and from the page where the questions are configured (see table above) select Order page contents from the context menu.

Figure 10 – Order Manipulation dialog – Generated interaction

Update models that use the modified generated interactions

The following Business Operation Models make use of the generated interactions listed above and needed to have the model mappings updated accordingly:

Amend Agent Name

Amend Personal Details

Create Consumer Sub-model

To do this:

List break

1 Check out each of the models.

2 Edit the model.

3 Find the generated interaction node in the model.

4 Select Edit Node.

5 Click OK.


30 of 57

6 The mappings should be refreshed.

7 Validate the model and Save it.

Update models to remove functionality relating to the capture and manipulation of title data

In the Vanilla profile as it currently stands it is necessary to change the ‘Amend Personal Details’ model so that functionality related to mapping gender to title is removed.

Essentially the ‘Match gender to title’ sub-model is removed along with the associated conditional branching nodes. The screen captures below detail what changes are required:

Before the change:

After the change


31 of 57

Update Scripts

There is only one Script that is used to construct the Name, that is Construct Addressee.

Supporting Definitions—Scripts

To do this:

Check out the Construct Addressee Script and select Properties from the context menu.

The Script used to read:

Addressee=Title+Name+Surname

This was changed to

Addressee=Surname+” “+Name

6.1.2 Capture gender information

The requirement is that the gender of the Consumer should be captured when a new Consumer is created. This applies to the Contact Centre and the Sample Mortgage Internet site.

Changes to configuration were made to:

Add Gender question to generated interactions.

Map the Gender output in the appropriate model to allow for the persistence of the data


Adding Gender question to generated interactions

The Create a consumer generated interaction domain was updated to include a question for gender on the Name page.

Supporting Definitions—Generated Interactions—Create a consumer—Contents—Name—Page contents.

Note that spaces have to be inside double quotes.


32 of 57

This generated interaction is used by both the Contact Centre and the Internet

channels so this was the only change required.

To do this:

There are two ways to add the extra question. Firstly by creating a new question (from the context menu select New then Question) and entering the appropriate details:

Figure 11 – Question properties dialog


33 of 57

Alternatively, if the question is used in another domain you can Copy the question

and Paste into the required place. We already had the question in the Personal Details Domain so we simply copied and pasted the question.

Mapping the gender output

The ‘Create Consumer Submodel’ was also updated to map the Gender output of the ‘Create a Consumer’ generated interaction out so that the data is made available for manipulation and saving.

It is also necessary to amend the input of the data manipulation node in the same model so that gender is one of the data elements passed into the Save Party node.

6.1.3 Address format and order

For more information on Address formats see the Country specific configuration user guide.


34 of 57

6.1.4 Removal of QAS Address Look up

QAS doesn’t provide a data file for Japan so the option to lookup addresses using QAS has was removed.

This is done by:

Select the Action button for the Number question in the following location:

Supporting Definitions—Generated Interactions—Address for new consumer—Contents—Address details—Page content–Number–Search for address

Delete by selecting Delete from the context menu or by pressing the Delete key.

6.1.5 Currency formatting

No configuration changes were made.

6.1.6 Date/time formatting

No configuration changes were made.

6.2 Web page changes The main areas that needed to be modified in order to reflect Japanese specific formats are detailed in the sections below.

6.2.1 Name format and order

The requirements for Name format is:

Surname followed by First name.

No Title or Initial

Changes were made to the following Web pages:

SCAllAgents.xslt

SCRetrieveAgentsToExpireTeam.xslt

WebConsumerDetails.xslt


SCAllAgents.xslt

This file is used to format a table of agents details. The only changes required were to swap the order of the surname and first name columns.

To do this:

The following lines were updated:

<header>

<headcol text="{$NLS_LBL_1}" sorted="true"/> <!—First Name

<headcol text="{$NLS_LBL_2}" sorted="true"/> <!—Surname

<headcol text="{$NLS_LBL_3}" sorted="true"/>


<headcol text="{$NLS_LBL_5}" sorted="false"/>


</header>

:

:


35 of 57

<xsl:template match="uie/_OUTPUTS/COLLECTION/child::*">

<top>

<expand uie="RetrieveRolesAndTeamsForSelectedAgent">

<xsl:attribute name="Input"><xsl:value-of select="PARTY_ID" /></xsl:attribute>

<topcol>

<xsl:attribute name="text"><xsl:value-of select="FirstName" /></xsl:attribute>

</topcol>

<topcol>

<xsl:attribute name="text"><xsl:value-of select="Surname" /></xsl:attribute>

</topcol>

:

And changed to :

<header>

<headcol text="{$NLS_LBL_2}" sorted="true"/> <!—Surname

<headcol text="{$NLS_LBL_1}" sorted="true"/> <!—First Name





</header>

:

:

<xsl:template match="uie/_OUTPUTS/COLLECTION/child::*">

<top>

<expand uie="RetrieveRolesAndTeamsForSelectedAgent">

<xsl:attribute name="Input"><xsl:value-of select="PARTY_ID" /></xsl:attribute>

<topcol>

<xsl:attribute name="text"><xsl:value-of select="Surname" /></xsl:attribute>

</topcol>

<topcol>

<xsl:attribute name="text"><xsl:value-of select="FirstName" /></xsl:attribute>

</topcol>

:

SCRetrieveAgentsToExpireTeam.xslt

Same change as was done for SCAllAgents.xslt.

WebConsumerDetails.xslt

The only changes required were to swap the order of the surname and first name fields.

To do this:

The following lines were updated:

<xsl:template match="COLLECTION">

<xsl:for-each select="Consumer">

<FONT class="TitleStyle3">

<xsl:value-of select="FirstName"/>

<xsl:value-of select="Surname"/>

</FONT>

</xsl:for-each>

</xsl:template>


36 of 57

And changed to :

<xsl:template match="COLLECTION">

<xsl:for-each select="Consumer">

<FONT class="TitleStyle3">

<xsl:value-of select="Surname"/>

<xsl:value-of select="FirstName"/>

</FONT>

</xsl:for-each>

</xsl:template>

6.2.2 Change order of search criteria

In order to change the order of search criteria fields in the Identify Party dialog. The file RetrieveSearchCriteria.xslt in the XSL folder has to be replaced by the file in the Localization folder on the CD-ROM.

Edit the file and modify the main XSLT root template to reflect the desired search criteria order as shown below. Note that the criteria are identified by the searchable attribute system name as specified in the configuration.

<xsl:template match="/">

<xsl:apply-templates

select="/uie/_OUTPUTS/COLLECTION/SearchCrite

ria[Name='Surname']"/>



ria[Name='FirstName']"/>



ria[Name='CorporateName']"/>



ria[Name='UserName']"/>

</xsl:template>

6.2.3 Currency formatting

The requirement is to make sure read-only currency fields are displayed using the correct Japanese format. This applies to generated interactions and views.

Portrait Foundation has been modified to use a generic currency format setting when displaying read-only values. The HTML for displaying currency value is generated using XSLT transformations. The currency format string is stored in xsl/i18n.xslt which is available in both the Contact Centre and Sample Mortgage Site applications.

Modifying i18n.xslt

There are two strings that represent the currency format, one that includes a currency symbol (used in Views) and another without a currency symbol which is used for Generated Interactions.

A line that contains the currency symbol (inside xsl/i18n.xslt) needs to be modified to match the exact currency symbol used in the Generated Interactions.

To do this:

The following lines were updated (in xsl\i18n.xslt):


37 of 57

<xsl:param name="NLS_TXT_ENCODING">UTF-8</xsl:param>

<xsl:param name="NLS_TXT_DIRECTION">LTR</xsl:param>

<xsl:param name="NLS_LOCALE">2048</xsl:param>

<xsl:param name="NLS_CURRENCY_HINT">GBP</xsl:param>

<xsl:param name="NLS_CURRENCY_FORMAT">#,###.00</xsl:param>

<xsl:param name="NLS_CURRENCY_FORMAT_WITH_SYMBOL">£#,###.00</xsl:param>

And changed to use the values shown below:




<xsl:param name="NLS_CURRENCY_HINT">円</xsl:param>

<xsl:param name="NLS_CURRENCY_FORMAT">#,###.</xsl:param>

<xsl:param name="NLS_CURRENCY_FORMAT_WITH_SYMBOL">￥#,###.</xsl:param>

6.2.4 Date/time formatting

Portrait Foundation uses the system’s default format setting to display dates and times. No extra configuration or Web changes are required in order to make Portrait Foundation display proper dates/times. However, time spans are formatted inside include\TopGeneric.js and the code has to be changed to reflect correct time span formatting.

Edit the file topgeneric.js, and edit the code highlighted inside the function R8ToTime to make it contain a localized representation of time duration.

function R8ToTime(dblData,strReturnType)

{

var intHours;

var intMins;

var intSecs;

intHours = Math.floor(dblData/(60*60));

intMins = Math.floor((dblData-(intHours*3600))/60);

intSecs = Math.floor(dblData - (intHours*3600) - (intMins*60));

if(strReturnType == null)

{

strReturnType = "STRING";

}

if(strReturnType == "ARRAY")

{

var arrReturnVal = new Array();

arrReturnVal[0] = intHours;

arrReturnVal[1] = intMins;

arrReturnVal[2] = intSecs;

return arrReturnVal;

}

if(strReturnType == "STRING")

{

if(intHours != 0)

{

return intHours + "h " + intMins + "m " + intSecs + "s";


38 of 57

}

if(intMins != 0)

{

return intMins + "m " + intSecs + "s";

}

return intSecs + "s";

}

}

6.3 Miscellaneous profile changes

6.3.1 Generation of contract number

The contract number generation script used by the mortgage profile uses three strings and the id of the contract to generate the contract number (a reference string that the user will see).

The format may not be relevant for different locales and can be updated to create a different string format if required.

The script that needs to be changed is Create Contract Number.

The Japanese version, for example, was updated to use the same value as the contract id.

If Len(ContractNumber) = 0 Then

ContractNumber = Left(ID, 12)

End If


39 of 57

Appendix A Web component I18N guidelines

This appendix provides coding guidelines to Web developers to allow them to create easily localizable Web components.

Historically, English has been the language of the software market. However, the need to expand the software market’s customer base has meant that successful software is required to accommodate the needs of non-English speakers, such as Far Eastern, Middle Eastern and European users.

Most software is developed and tested in an English environment. If the programmer is not aware of culture-specific issues, the resulting source code will not be ready for direct deployment in certain markets. This is one reason why software has to pass through a number of stages before being deployed into the international market.

Firstly, we will define the difference between some key terms that are used in this document.

A.1 Globalization Globalization involves making company-wide preparations in order to enter the international marketplace. Globalization covers anything that needs to be done differently to optimise international success.

A.2 Internationalization Internationalization involves altering all the market-generic aspects of a product to promote easier, cheaper, faster and higher-quality localization.

Internationalization generally involves a one-time, up-front investment. In the context of this document, internationalization refers to the code changes that are made to ensure that a product can be localized and that information is presented in a format to which the end user is accustomed.

A.3 Localization Localization covers anything that involves altering market-specific aspects of a product before it can be competitively introduced into another country. In its simplest form, localization refers to the translation of strings within the product, enabling the user to view it in a target language.

The diagram in Figure 12 illustrates the various definitions.


40 of 57

Figure 12 – Terminology

Internationalization

Globalization

Localization Marketing/Strategy Other Issues

Development

Technical

QA/Testing

Translation

Process/Work

Project Management

International Web

Promotion

Marketing

Legal

Sales

Distribution

QA/Testing Business Plan Education

A.4 Locale The locale is the user’s environment, which depends on both language and country. In Windows, the locale is set on the Control Panel by selecting the supported language/country pairs. The Windows environment also allows multiple locales on a single machine with a certain locale set as the default.

Each locale is identified with a language and a country. Arabic, for example, has around sixteen locales, one for each country in the Arab world. Microsoft has created unique long values to identify each locale.

A.4.1 Locale information

Many countries can use the same language, but each country has its own currency symbol, date format, and numeric format. For example, USA and UK use English, but the currency symbol, date format and numeric format are all different. The supported locale data is listed in Table 1.

Table 1 – Locale data

Locale data

Long date format

Short date format

Input date mode

Date separator

Time format

Time separator

AM/PM symbol

Currency symbol

Monetary thousands separator

Monetary decimal point

Thousands separator

Decimal point

This locale information should be considered when displaying information to the user, such as date and currency. The Win32 SDK provides the API functions to facilitate this. For example, GetDateFormat and GetTimeFormat return a single string each. The following code shows how retrieve the long German date format string (Germany):


41 of 57

DWORD dwRC = ERROR_SUCCESS

LPTSTR pszDate = (LPTSTR) GlobalAlloc(GPTR, MEMSIZE(nLen + 1));

if ( !pszDate )

return (GetLastError());

int nLen = GetDateFormat(1031, //Use German Locale.

DATE_LONGDATE, // Flags are passed into this function.

NULL, // Use current system time.

pszDateFormat, // format selected by user

pszDate, // used for formatted date

nLen); // used for date buffer length

if ( nLen == 0 ) {

dwRC = GetLastError();

GlobalFree(pszDate);

return (dwRC);

}

Server-side Visual Basic script contains a set of API and data types that are locale-aware. However, client-side JavaScript lacks locale support and may cause problems when attempting to handle more than one locale on the client side.

A.4.2 Character set

Not all languages use an exclusively alphabetical system to write. For example, Far Eastern languages, such as Japanese, use pictorial representations of words, called glyphs or ideographs.

The problem with this for the computer representation of Far Eastern languages is that the number of different characters that may be constructed can be several thousand. This is far more than the limit of 256 characters that has been traditionally considered acceptable for the alphabetically-based languages commonly used in the rest of the world.

European languages use various 8-bit coding systems. This gives ample character space for symbols, upper and lower case letters, diacritical letters and numerals. However, there are a number of different coding systems available. Some contain extra characters for the Greek or Cyrillic alphabets. Some have a different set of diacritical characters suitable for different geographical regions. Each different encoding is called a code page. Most versions of Windows for Western European and American versions use the same code page, variously called ANSI, Windows Latin 1 or ISO-8859-1.

Unfortunately, as these code pages are limited to 256 characters each, they are totally unsuitable for encoding the large number of characters required for Far Eastern languages. Two methods are currently used to resolve this problem. The most obvious solution is to use a larger number of bits in the encoding system. Unicode uses this solution by using a 16-bit word to describe each character. The other solution is to use a multi-byte encoding system. A multi-byte system is one that can use different encoding lengths for different types of characters. For

example, it is usual for the standard ASCII characters to remain as single-byte 8-bit characters. However, the Far Eastern characters would be assigned 2-byte 16-bit character codes. The codes would be arranged so that it is possible to tell if the character code is 8-bit or 16-bit.

Portrait’s Web output is encoded using UTF-8 which is a variant of Unicode. This encoding is supported by all Web browsers and offers the flexibility of displaying multi-lingual text on a single page. The application’s encoding setting is specified in the Web.Config file in the application folder.


42 of 57

A.5 Practical guidelines for Web Developers The following guidelines are based on the existing implementation of the internationalized Portrait Contact Centre Vanilla Profile. The following code domains are considered:

ASP.Net code

Client-side scripting

XSL transformations

In order to develop an internationalized and locale-aware Web application you need to consider the following areas of functionality:

Resources translation. All translatable resources should be identified. This allows you to use the translation tool, which is able to extract the translatable strings from the source code, translate them, and merge them back to the source code.

Setting the proper locale and character set for run-time environment.

Data formats and input validations.

Keyboard shortcuts handling.

HTML layout dimensions and presentation styles.

The client-side scripting guidelines use Internet Explorer-specific functionality. Therefore they should only be applied in a controlled environment (intranet applications such as the Contact Centre).

Below is the list of changes in application code and structure compared to the standard non-internationalized Portrait Contact Centre application.

All displayable hard-coded strings in XSLT and Jscript files have been substituted with variables.

Two additional internationalization-related include files have been introduced:

o includes\I18N.vbs

o xsl\i18N.xslt

Script languages have been specified.

Hard-coded data formats have been substituted with the locale-aware formatting and parsing functions.

This is an excerpt from the XSLT page to illustrate all the differences for the XSL transformations.

<?xml version="1.0" encoding="UTF-8"?> Specify template encoding



<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:include href="i18N.xslt" /> Include locale-related common variables

<xsl:output method="html" version="4.0" encoding="{$NLS_TXT_ENCODING}"/> Specify HTML

output encoding

 mark the start of the translatable variables initialization

list

. . . Translatable variables initialization goes here

 mark the end of the translatable resources initialization list


43 of 57

. . .

</xsl:stylesheet>

The changes are described in more detail in the sections below.

A.5.1 ASP.Net code

Resources translation

Using Server Controls

Portrait Foundation’s applications are built using the controls provided by the ADK. These controls are self localizing; so as long as the pages are using these controls then they are by default localizable.

There are equivalent controls for all the standard ASP.NET components. These controls are listed below

Button

CancelButton

CheckBox

CurrencyEdit

CustomGrid

DataGrid

DateEdit

DropDownList

GridActionButton

Label

ListBox

NameText

NumericEdit

OKButton

RadioButton

ShutterView

StringEdit

TimeEdit

TimeSelect

TitleText

All controls that display text, such as, NameText, Label and TitleText retrieve their text from the resource catalogue at run time. So, by simply dropping labels on the page, they will be localized automatically at run time.

The resource catalogue that holds the text for the controls is generated automatically using Portrait Foundation’s localization add-in which is shipped on the release media. Please refer to the Localization Add-in User Guide for more information on the add-in.


44 of 57

Developers should not code text in the HTML directly as that text will never be

picked up by the localization add-in. Instead, they should substitute server controls. For example,

<p> This is a test </p>

should become

<p><amc:label runat=server id=testLbl>This is a test </cc1:label></p>

Dynamic resource manipulation

It maybe necessary to use text that cannot be set using a server control at design time. For example, a label may hold different values depending on different scenarios, so their text has to be set dynamically at run time.

For example

if (flag == 1)

Label1.Text = "flag is one";

else

Label1.Text = "Flag is not one";

In order to resolve this issue, the hard coded messages ‘flag is one’ and ‘flag is not one’ have to be added to the common resource catalogue (commonresources.resx) and given unique keys (say Key1, Key2 respectively).

Then the code will change to

if (flag == 1)

Label1.Text = Base.GetResourceString("Key1", "flag is one");

else

Label1.Text = Base.GetResourceString("Key2", "Flag is not

one");

The Page object provides the function GetResourceString which searches the catalogue for the string which key is passed as a parameter. The second parameter is a default value that is returned if the string does not exist in the resource catalogue.

Passing text from server side components to client side code.

It maybe necessary that the client side code (Jscript) displays text that is produced by the server side components. The easiest way to expose that text to the JavaScript code is by registering it in a hidden field in produced form as shown in the example below

ASPX code

<script language = jscript>

function displayAlert()

{

alert(PageForm.Message1.value);

}

</script>

<body>

<form id="PageForm">

</form>

.CS code


45 of 57

void OnLoad()

{

string message = Page.GetResourceString("Key1", "Message 1");

Page.RegisterHiddenFields("Message1", message);

…

…

}

Locale and character set

Portrait Foundation uses the UTF-8 encoding for all its Response outputs. It also uses the system’s default locale in order to handle locale sensitive data, such as, dates and time.

It is recommended that these settings are left as they are. However, the developer can override these settings by editing the web.config file in the application’s folder.

Data formats and input validations

The ADK contain specialised DateEdit, CurrencyEdit and TimeEdit controls. These controls incorporate validation and masking facility that force the user to type only valid formats that conform the server’s default locale/culture.

It is recommended that developers make use of these controls as they incorporate rich functionality that helps avoid data corruption.

The .NET platform provides a rich Convert class that exposes static methods to convert between all the basic .NET framework types (date/time/string/number). This class should used when converting string data returned from the form to its equivalent type.

Special Date/Time/Currency formatter classes are also available. These can be used when special formatting is required, such as, format a DateTime object to a short date string.

A.5.2 Client-side scripting

Include file encoding

All client-side include files should be saved in UTF-8 format.

Resource translation

If you use an external JavaScript include file, apply the template as shown below:

//NLS_TEXT_BEGIN

var NLS_PU_LBL_1 = "Copy"; //Label

var NLS_PU_LBL_2 = "Paste"; //Label

var NLS_PU_LBL_4 = "About"; //Label

var NLS_PU_LBL_5 = "Refresh"; //Label

var NLS_PU_LBL_6 = "Allow IE context menu"; //Label

var NLS_PU_LBL_7 = "View source"; //Label

var NLS_PU_LBL_8 = "System console"; //Label

//NLS_TEXT_END

Locales, formats, validations

Always use the provided server controls to make sure data is validated properly before being sent back to the CRM server. These control already have their own Jscript framework for validation. However, if it is absolutely necessary to use client side scripting, then follow the instructions below.


46 of 57

Never assume that data will be entered in a specific format. JavaScript does not

provide completely locale-aware functionality, but Visual Basic script does. Because of interoperability available between JavaScript and Visual Basic script, you could use locale-aware functionality of Visual Basic script inside the JavaScript code. However, it is not possible to call standard runtime Visual Basic script functions from your JavaScript code. Therefore, you should use the Visual Basic script wrapping functions provided in the i18N.vbs include file. Link this file to your page whenever you do something related to locales on the client side. Your page should look similar to this:

<HTML>

<HEAD>

<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=<%=NLS_HTML_CHARSET%>">

<link rel="stylesheet" type="text/css" href="includes/Dialog.css"/>

<script language='VBScript' src='includes/i18N.vbs'></script>

<script language="JavaScript" src="includes/Generic.js"></script>

. . .

Note the following points:

List break

1 JavaScript and Visual Basic script Date data types have different internal representations. Therefore you should convert the Date value whenever you pass it as an argument to a Visual Basic script function, and retrieve it as a result from Visual Basic script function.

To pass a Date value, use getVarDate(), for example:

VBFunctionAcceptingDate(jsDate.getVarDate())

To retrieve a Date value, use the Date() constructor to create a new Date() object from the Visual Basic script variant value. For example:

var jsDate = new Date(VBFunctionReturningDate())

2 Place the link to the i18N.vbs include file first if you have more than one script file to link into the page.

3 Always specify the script language in the HTML code. If you fail to do this, behaviour of your script can be unpredictable. For example:

<script language="JavaScript" src="includes/Generic.js"></script>

. . .

<input type="radio" name="TimeDate" onclick="JavaScript:fnTimes();">

. . .

<input type="radio" name="TimeDate" onclick="JavaScript:{fun1(); .; .; fun2();}">

. . .

Below is an illustration from a i18N.vbs file, to give you an idea of functionality

implemented.

SetLocale(0)

. . .

function IsValidDate (AVal)

. . .

function String2Date(AVal)

. . .

function Date2String(AVal, AFormat)

. . .

function AddDateInterval (ADate, AInterval, ANumber)

. . .


47 of 57

SetLocale(0) instructs the script engine to use the browser’s default locale.

A.5.3 XSL transformations

Resources translation

The same technique used in the Jscript code should be applied for XSL template translations. Use the following example as a template:



<xsl:param name="NLS_LBL_1">Satisfied</xsl:param>

<xsl:param name="NLS_LBL_2">Type</xsl:param>

<xsl:param name="NLS_LBL_3">Number</xsl:param>



. . .

<xsl:if test=".=$NLS_LBL_1">

<xsl:attribute name="selected">true</xsl:attribute>

</xsl:if>

. . .

<treeview>

<header>

<headcol text="{$NLS_LBL_2}"/>

. . .

<topcol>

<xsl:attribute name="text"><xsl:value-of select="$NLS_LBL_3"/></xsl:attribute>

</topcol>

. . .

Locales, code pages, formats, validations

Make sure that your XSL template has UTF-8 encoding:

<?xml version="1.0" encoding="UTF-8" ?>

An include file is provided (i18N.xslt) to use locale-related settings. This file defines specific locale and language-dependent settings, and contains following code:

<?xml version="1.0" encoding="UTF-8" ?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns="http://www.w3.org/TR/REC-html40">




</xsl:stylesheet>

You could extend the these settings according to your requirements.

Use the NLS_TXT_ENCODING value to specify encoding of the transformation output. It is recommended that this value is always set to UTF-8. Your XSLT file should look similar to this:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns:msxsl="urn:schemas-microsoft-com:xslt">

<xsl:include href="i18N.xslt" />

<xsl:output method="html" version="4.0" encoding="{$NLS_TXT_ENCODING}"/>

. . .


48 of 57

If you want to execute the locale-aware script during the transformation,

implement this script using Visual Basic script. And don’t forget to let the script know about the locale you want to run it in. For example:

<msxsl:script language="VBScript" implements-prefix="user">

<![CDATA[

function fnAvailable(strStartDate, strEndDate, intLocale)

setLocale(intLocale)

blnAvailable = IsDate(strStartDate) OR IsDate(strEndDate)

. . .

end function

]]>

</msxsl:script>

. . .

<xsl:value-of select="user:fnAvailable(string(EFFECTIVE_FROM), string(EFFECTIVE_TO),

number($NLS_LOCALE))"/>

. . .

A.5.4 HTML layout

It is very important to understand that your internationalized application might be localized for any possible language and culture. Therefore, you should prepare your application to have a flexible HTML presentation layout. Consider the following:

Sizes, dimensions and directions

The same phrase in different languages may be significantly different in the number of words and letters used. As a general rule, you should assume that any English text might be expanded up to four times in size after translation in to another language. Moreover, the layout of your page could be mirrored in case of localization for Middle Eastern languages (Arabic, Hebrew). These facts apply some constraints to the design of your HTML layouts.

List break

1 Think carefully when you decide to hard-code element sizes, especially tables and cells.

2 Do your best to implement a flexible re-sizable layout that will not break your page design if the text becomes either bigger or smaller. Use graphical design wisely.

3 The font size could change as well—the Japanese glyph is a good example. Use localized Cascading Style Sheets (CSS) for different languages to implement different fonts and their sizes, colour schemes and so on.


49 of 57

Appendix B Locale IDs

Language - Country/Region Short String

LCID Decimal

LCID Hexadecimal

Afrikaans - South Africa af 1078 436

Albanian - Albania sq 1052 041c

Amharic - Ethiopia 1118 045e

Arabic - Algeria ar-dz 5121 1401

Arabic - Bahrain ar-bh 15361 3c01

Arabic - Egypt ar-eg 3073 0c01

Arabic - Iraq ar-iq 2049 801

Arabic - Jordan ar-jo 11265 2c01

Arabic - Kuwait ar-kw 13313 3401

Arabic - Lebanon ar-lb 12289 3001

Arabic - Libya ar-ly 4097 1001

Arabic - Morocco ar-ma 6145 1801

Arabic - Oman ar-om 8193 2001

Arabic - Qatar ar-qa 16385 4001

Arabic - Saudi Arabia ar-sa 1025 401

Arabic - Syria ar-sy 10241 2801

Arabic - Tunisia ar-tn 7169 1c01

Arabic - U.A.E. ar-ae 14337 3801

Arabic - Yemen ar-ye 9217 2401

Armenian - Armenia hy 1067 042b

Assamese 1101 044d

Azeri (Cyrillic) az-az 2092 082c

Azeri (Latin) az-az 1068 042c


50 of 57

Basque eu 1069 042d

Belarusian be 1059 423

Bengali 1093 445

Bengali (Bangladesh) 2117 845

Bosnian (Bosnia/Herzegovina) 5146 141A

Bulgarian bg 1026 402

Burmese 1109 455

Catalan ca 1027 403

Cherokee - United States 1116 045c

Chinese - Hong Kong SAR 3078 0c04

Chinese - Macao SAR zh-mo 5124 1404

Chinese - People's Republic of China

zh-cn 2052 804

Chinese - Singapore zh-sg 4100 1004

Chinese - Taiwan zh-tw 1028 404

Croatian hr 1050 041a

Croatian (Bosnia/Herzegovina) 4122 101a

Czech cs 1029 405

Danish da 1030 406

Divehi 1125 465

Dutch - Belgium nl-be 2067 813

Dutch - Netherlands nl-nl 1043 413

Edo 1126 466

English - Australia en-au 3081 0c09

English - Belize en-bz 10249 2809

English - Canada en-ca 4105 1009

English - Caribbean en-cb 9225 2409


51 of 57

English - Hong Kong SAR 15369 3c09

English - India 16393 4009

English - Indonesia 14345 3809

English - Ireland en-ie 6153 1809

English - Jamaica en-jm 8201 2009

English - Malaysia 17417 4409

English - New Zealand en-nz 5129 1409

English - Philippines en-ph 13321 3409

English - Singapore 18441 4809

English - South Africa en-za 7177 1c09

English - Trinidad en-tt 11273 2c09

English - United Kingdom en-gb 2057 809

English - United States en-us 1033 409

English - Zimbabwe 12297 3009

Estonian 10061 425

Faroese fo 1080 438

Farsi fa 1065 429

Filipino 1124 464

Finnish fi 1035 040b

French - Belgium fr-be 2060 080c

French - Cameroon 11276 2c0c

French - Canada fr-ca 3084 0c0c

French - Cote d'Ivoire 12300 300c

French - Democratic Rep. of Congo 9228 240c

French - France fr-fr 1036 040c

French - Haiti 15372 3c0c

French - Luxembourg fr-lu 5132 140c


52 of 57

French - Mali 13324 340c

French - Monaco 6156 180c

French - Morocco 14348 380c

French - North Africa 58380 e40c

French - Reunion 8204 200c

French - Senegal 10252 280c

French - Switzerland fr-ch 4108 100c

French - West Indies 7180 1c0c

Frisian - Netherlands 1122 462

Fulfulde - Nigeria 1127 467

FYRO Macedonian mk 1071 042f

Gaelic (Ireland) gd-ie 2108 083c

Gaelic (Scotland) gd 1084 043c

Galician 1110 456

Georgian 1079 437

German - Austria de-at 3079 0c07

German - Germany de-de 1031 407

German - Liechtenstein de-li 5127 1407

German - Luxembourg de-lu 4103 1007

German - Switzerland de-ch 2055 807

Greek el 1032 408

Guarani - Paraguay 1140 474

Gujarati 1095 447

Hausa - Nigeria 1128 468

Hawaiian - United States 1141 475

Hebrew he 1037 040d

HID (Human Interface Device) 1279 04ff


53 of 57

Hindi hi 1081 439

Hungarian hu 1038 040e

Ibibio - Nigeria hu 1038 469

Icelandic is 1039 040f

Igbo - Nigeria 1136 470

Indonesian id 1057 421

Inuktitut 1117 045d

Italian - Italy it-it 1040 410

Italian - Switzerland it-ch 2064 810

Japanese ja-jp 1041 411

Kannada 1099 044b

Kanuri - Nigeria 1137 471

Kashmiri 2144 860

Kashmiri (Arabic) 1120 460

Kazakh 1087 043f

Khmer 1107 453

Konkani 1111 457

Korean ko 1042 412

Kyrgyz (Cyrillic) 1088 440

Lao 1108 454

Latin 1142 476

Latvian lv 1062 426

Lithuanian lt 1063 427

Malay - Brunei Darussalam ms-bn 2110 083e

Malay - Malaysia ms-my 1086 043e

Malayalam 1100 044c

Maltese mt 1082 043a


54 of 57

Manipuri 1112 458

Maori - New Zealand 1153 481

Marathi mr 1102 044e

Mongolian (Cyrillic) 1104 450

Mongolian (Mongolian) 2128 850

Nepali 1121 461

Nepali - India 407 861

Norwegian (Bokmål) no-no 1044 414

Norwegian (Nynorsk) no-no 2068 814

Oriya 1096 448

Oromo 1138 472

Papiamentu 1145 479

Pashto 1123 463

Polish pl 1045 415

Portuguese - Brazil pt-br 1046 416

Portuguese - Portugal pt-pt 2070 816

Punjabi 1094 446

Punjabi (Pakistan) 2118 846

Quecha - Bolivia 1131 046B

Quecha - Ecuador 2155 086B

Quecha - Peru 3179 0C6B

Rhaeto-Romanic rm 1047 417

Romanian ro 1048 418

Romanian - Moldava ro-mo 2072 818

Russian ru 1049 419

Russian - Moldava ru-mo 2073 819

Sami (Lappish) 1083 043b


55 of 57

Sanskrit sa 1103 044f

Sepedi 1132 046c

Serbian (Cyrillic) sr-sp 3098 0c1a

Serbian (Latin) sr-sp 2074 081a

Sindhi - India 1113 459

Sindhi - Pakistan 2137 859

Sinhalese - Sri Lanka 1115 045b

Slovak sk 1051 041b

Slovenian sl 1060 424

Somali 1143 477

Sorbian sb 1070 042e

Spanish - Argentina es-ar 11274 2c0a

Spanish - Bolivia es-bo 16394 400a

Spanish - Chile es-cl 13322 340a

Spanish - Colombia es-co 9226 240a

Spanish - Costa Rica es-cr 5130 140a

Spanish - Dominican Republic es-do 7178 1c0a

Spanish - Ecuador es-ec 12298 300a

Spanish - El Salvador es-sv 17418 440a

Spanish - Guatemala es-gt 4106 100a

Spanish - Honduras es-hn 18442 480a

Spanish - Latin America 58378 e40a

Spanish - Mexico es-mx 2058 080a

Spanish - Nicaragua es-ni 19466 4c0a

Spanish - Panama es-pa 6154 180a

Spanish - Paraguay es-py 15370 3c0a

Spanish - Peru es-pe 10250 280a


56 of 57

Spanish - Puerto Rico es-pr 20490 500a

Spanish - Spain (Modern Sort) 3082 0c0a

Spanish - Spain (Traditional Sort) es-es 1034 040a

Spanish - United States 21514 540a

Spanish - Uruguay es-uy 14346 380a

Spanish - Venezuela es-ve 8202 200a

Sutu sx 1072 430

Swahili sw 1089 441

Swedish sv-se 1053 041d

Swedish - Finland sv-fi 2077 081d

Syriac 1114 045a

Tajik 1064 428

Tamazight (Arabic) 414 045f

Tamazight (Latin) 1119 085f

Tamil ta 1097 449

Tatar tt 1092 444

Telugu 1098 044a

Thai th 1054 041e

Tibetan - Bhutan 2129 851

Tibetan - People's Republic of China

1105 451

Tigrigna - Eritrea 2163 873

Tigrigna - Ethiopia 1139 473

Tsonga ts 1073 431

Tswana tn 1074 432

Turkish tr 1055 041f

Turkmen 1090 442


57 of 57

Uighur - China 1152 480

Ukrainian uk 1058 422

Urdu ur 1056 420

Urdu - India 2080 820

Uzbek (Cyrillic) uz-uz 2115 843

Uzbek (Latin) uz-uz 1091 443

Venda 1075 433

Vietnamese vi 1066 042a

Welsh 1106 452

Xhosa xh 1076 434

Yi 1144 478

Yiddish yi 1085 043d

Yoruba 1130 046a

Zulu zu 1077 435

Documents

Portrait Foundation v5.0.4 Localizing ASP.NET Applications ... · powerful inbound and outbound campaign management, and best-in-class business process integration to deliver real-time