User interface code in TOPICA is implemented using the ASP.NET Webforms technology. Each Webform consist of two files:

• An .ASPX file containing "mark up" (plain HTML mixed with ASP.NET web control declarations).

• An .ASPX.CS file (= the "code behind") containing C# code, that controls the user interface (initializes controls on the page, handles events, etc.).

The standard ASP.NET way to implement localization is to use the meta:resourcekey attributes on the web controls. The value of this attribute refers to a resource name in a local (page specific) resource file. When this is used correctly, ASP.NET automatically handles localization of the property values of the controls. E.g. texts etc. are read from the resource file that corresponds to the current culture.

It is tempting to write texts like field labels, error/warning messages, etc. directly into the HTML markup (as "literals"). But this is not localizable - so this should be avoided.

Instead of literal texts, use Localize controls with meta:resourcekey attributes.

When implementing Webforms (especially when working in the "quick and dirty" way), it may be tempting to hard code texts (error messages etc.) in the "code behind". This a "no-no", because it hinders localization.

Texts should be read from resources. Resources may be local (page specific) or global:

• Local resources should be used in most cases. The recommended way to access texts in local resources from "code behind", is to place some hidden controls (e.g. Localize controls with meta:resourcekey attributes) in the .ASPX, and then refer to the properties of these controls from "code behind".

  Use of local resources makes it easy to handle localization of texts etc. one page (webform) at a time.

• Global resources should be used only, when a text must be the same on ALL pages (webforms) - updating this text in one place (in the global resource file) will update all ocurrencies of this text in all pages of the application.

Several control types may have shortcuts defined on them. The shortcut key combination typically involves a letter that is contained in the control text - and that letter should be marked as shortcut key (e.g. by underlining it), so that the user easily can identify the shortcut.

When localizing texts on controls, that have shortcuts defined on them, the shortcut key-combination must typically be localized, too.

TOPICA has built-in functionality to handle localization of shortcuts, i.e. properties should be defined in local resource files. TOPICA automatically underlines the first letter in the control text, that matches the letter of the shortcut key combination.

• Some control types (notably tabs in tabsets) have the AccessKey property. Such shortcuts are activated by the key kombination Alt+<AccessKey>, Enter (that is: first Alt+<letter> - then Enter. This uses the built-in access key feature in HTML.

• Standard ASP.NET button controls do NOT support underlining letters in the button text - nor do they have the AccessKey property. Therefore, TOPICA contains the user control ShortcutControl. The ShortcutControl works in this way:

  • The ShortcutControl should be placed in the .ASPX file directly after the ASP.NET button control, that should have a shortcut. Set the values of the property ControlId to the ID of the ASP.NET button control.

  • The value of the ShortcutControl's property KeyCombination is defined in the local resource file.

  • The ShortcutControl hides the referenced ASP.NET button, and displays a <button> element with the same text, except for the added underlining.

  • The ShortcutControl generates JavaScript code that catches keypresses and activates the corresponding button. This mechanism allows any key combination to be used - e.g. Ctrl+Alt+<letter> or Ctrl+Shift+<letter> (Enter is NOT used to activate the control in this case).

The system relies on, that the current culture name is passed to all pages (webforms) in the application.

When constructing URL's to navigate from page to page, always use the property CommonParameters (inherited from the base page). This will ensure, that the culture name (along with other standard parameters like the name of the configuration) is passed in the query string.

JavaScript is used for client-side validations etc. - and as such must often display messages (information, warnings, errors) to the user.

For "global" JavaScript functions (i.e. code in include files used on several pages), use the tables defined in JavaScript/Messages/<culture>.js to localize the messages.

For "local" JavaScript functions (used on a single page), one could use hidden web controls (with meta:resourcekey attributes) in the .ASPX, and let the JavaScript code get the text from these controls.

Localization is primarily for the benefit of end users. End users will expect the software they use on a daily base to be in their own language. Therefore, most of the user interface for the functionality described in Applicaton Guide - at least the part the is meant for ens users - should be localizable.

While TOPICA does display end user oriented user interface, it is also a development tool. Developers are used to tools that only exist with english user interface. Framework developers, application developers, and configurators regularly work with tools like Visual Studio and SQL Server Management Studio, that only have english language user interfaces. Therefore, these users of TOPICA should have no problems working with english language user interface. Large parts of the functionality in TOPICA is NOT localized, i.e. the user interface will be in english no matter what "culture" is selected. This goes for the forms template / structure file editor, everything in the "Tools / Framework Tools" menu, and most of the debugging / testing functionality built into TOPICA.

These are the steps to follow, when adding support for a new culture to the framework

1. Add a new folder of database scripts for the new culture. The folder's name should equal the culture name. So, to localize the system to french, you should name the folder fr-FR. Each culture specific folder must contain the same set of files as they serve as interface for the framework:

   Tip
   As it is important that all required functions and tables are available for the framework in all cultures it is recommended to make a copy of an existing set of scripts and edit them to match the current culture.

   Name	Purpose
   TOPICA.sql	Localize lookup texts etc. used by the TOPICA framework.  Caution To avoid breaking dependencies like contraints only edit the captions in the insert and update statements.
   NationalId.sql	Define properties of the national id system used in the country, e.g. number of characters, functions for validation, converting between internal and external formats, etc. This script MUST define a standard set of functions.
   Extensions.sql	Define any tables needed to implement culture-specific patient properties. Before editing this file, you must have an idea of that is needed in the specific culture as it vary from culture to culture. It is not just a translation of texts. If no culture-specific properties are needed you can ommit this script.
   Organization.sql	Optionally define a standard organizations structure and contents.
   ZipCode.sql	Optionally define zip codes.  Note If zipcodes are not defined, you will not be able to use zip codes in addresses in configurations based on the database.

2. Construct resource files with texts for the new culture (for the web forms).

   • To localize to for example french, you could copy all *.en.resx files to *.fr.resx (remember to copy both local and global resource files).

   • After copying, translate all texts in the new *.fr.resx files.

3. Construct a new file in the folder JavaScript/Messages (for messages from JavaScript).

   • To localize to for example french, you could copy JavaScript/Messages.en-GB.js to JavaScript/Messages.fr-FR.js.

   • After copying, translate all texts in the new JavaScript/Messages.fr-FR.js file.

     Caution
     It is important only to translate the values as the javascripts in the framework expects to find the keys

4. Construct a new folder in the folder Help (for help files).

   • To localize to for example french, you could copy en to fr.

   • After copying, translate the text in all the files in the new Help/fr folder.

     Caution
     Do not change the names of the individual help files as they must match the name of the form, they belong to.

Normally, the database defines the culture. So, to view the user interface in N different cultures, you would have to build N databases and N configurations - and alternating between these configurations.

This is cumbersome. So to ease testing and debugging of localization, a few buid-in debug tools exist:

• Turn on "debug mode". The main menu will display a dropdown list with one option per supported culture. The user may select any culture from this list.

• Set .config file parameter key="Culture.Select" value="true". This will result in same dropwodn as "debug mode" AND add a group of radio buttons to the login page - one button per each supported culture. The culture defined by the database is selected per default, but the user may select a different option.

Remember that the configuration and the database are still only built in one culture/language. - so texts defined by the configuration or the database will not change. Only the texts etc. defined in the framework will change to be displayed according to the culture, the user selects.

The result is, that some parts of the user interface are displayed in one language, and some other parts are displayed in another language. Clearly, this should not be used in "real life" - but it is a handy feature for testing localization of the framework.

Other Resources