416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
This is the support page for the legacy Dundas Dashboard application. For assistance with the current Dundas BI application please click here.
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Multi-Language Support in Dundas Dashboard

Hide navigation
RSS
Modified on Mon, 16 Jun 2014 11:45 AM Categorized as Administration, Configuration, Level-Intermediate, Licenses, User Interface, Viewer
Click to return to: Documentation


Overview

The Dashboard Viewer can be configured to display application text (e.g. text appearing in toolbars, dialogs and wizards) in a language that is different than the default (i.e. English). This is achieved via a set of XML translation/localization files that is included with the installation and which can be copied and then customized for a target language. Currently, Dundas Dashboard does not ship with alternate language translations, but this could be added in a future release, or it can be accomplished by third parties or even your own organization.

Dundas Dashboard also provides proper support for right-to-left languages such as Arabic. For example, you can now enter text naturally in the property grid (while designing a dashboard) when the input language is set to Arabic in Windows.

The multi-language support in Dundas Dashboard is focused primarily on users who view and interact with dashboards via the Viewer.aspx URL (e.g. http://mydashsvr:7000/Viewer.aspx), or through a custom application that integrates the dashboard viewer.

When you access Dundas Dashboard via the regular application URL (e.g. http://mydashsvr:7000/Default.aspx), English is the language that is used and the localization features do not apply. (However, you will have the option of configuring the regular application to use a specific English culture such as en-US or en-GB.)

Note: In the context of this article, the term viewing-time refers to the use of Viewer.aspx or an embedded dashboard viewer.

Background

Locale and Culture

The terms, locale and culture, are often used interchangeably when discussing support for multiple languages in a software application. A locale or culture is a collection of settings that defines a user's language, country and preferences for viewing specific kinds of information in a user interface, such as:

  • numbers
  • dates and times
  • currency

Each culture has a name which generally consists of two parts:

  1. A two-letter lowercase culture code associated with a language.
  2. A two-letter uppercase subculture code associated with a country or region.

Example culture names:

Culture NameLanguage (Country/Region)
en-USEnglish (United States)
en-CAEnglish (Canada)
fr-FRFrench (France)
de-DEGerman (Germany)

For more information about cultures in .NET and Silverlight, see the MSDN article regarding the CultureInfo class.

Internationalization

Internationalization, also known as i18n, refers to the process of designing a software application in a manner that allows it to be easily adapted to different languages or used in other countries and regions around the world. Using Dundas Dashboard as an example, the dashboard viewer component has now been internationalized via the use of XML localization files. Supporting a new language does not require a new version of the application to be released. All that is needed is to create and install a set of localization files for the desired language. Creating localization files involves translating each of the strings that appears in the user interface of the dashboard viewer.

Localization

Localization, or L10n, refers to the process of configuring an internationalized software application for use under a specific language or culture. In terms of Dundas Dashboard, this refers to the preparation and installation of a set of XML files which contain translated text for a target language or culture.

Globalization

Globalization combines internationalization and localization in order to describe a software application that provides the user with a choice of languages or cultures from which they can select at run-time. In terms of Dundas Dashboard, this could refer to the dropdown list (in the dashboard viewer's login screen) that lets users choose the culture they want to use for viewing and interacting with dashboards (assuming suitable translations have been prepared and installed).

Right-to-left

As mentioned in the overview, Dundas Dashboard supports right-to-left languages such as Arabic and Hebrew. Follow this example to see how this works:

  1. Create a new dashboard and drag a label control to the canvas.
    Create a label.
  2. Go to your Windows language bar and change the input language to one that flows right-to-left.
    Change the input language.
  3. Click the label's Text property value to open a dialog which lets you enter text for the label.
    Type the right-to-left text.
  4. Observe that the text flows right-to-left as you type in addition to being displayed in the proper language.
  5. You can now save and preview your dashboard to see the label.

Default culture

Upon installation, the Dundas Dashboard application is configured with a default culture that applies to all users. At viewing-time, this culture is used to display numbers, dates and currency amounts in the appropriate format.

The default culture for the application can be changed via the defaultCulture element in the Dundas Dashboard Configuration File. If this element is missing, commented out, or its value is set to Auto, then the default culture is determined automatically based on the culture of the Windows user account that is running the Dundas Dashboard app pool in IIS. This ‘automatic’ culture may be en-US for English (United States), for example. You can override the automatic culture by adding a globalization element to the Dundas Dashboard Web.config file in IIS 6, or by using IIS Manager in IIS 7.

Changing the default culture for the application

The following example shows how to change the default culture in the configuration file and the effect this has on the display of dashboards at viewing-time.

Create a basic dashboard as follows:

  1. Log in to Dundas Dashboard as a designer or developer.
  2. Create a new dashboard.
  3. Drag a label control from the toolbox to the canvas and make it wider.
  4. Add a Load interaction script to the dashboard that modifies the label text to show the current date:
    Label1.Text = DateTime.Now.ToLongDateString();
  5. Save, then preview the dashboard.
    Date displayed with default culture.

Next, modify the configuration file:

  1. Log out of Dundas Dashboard.
  2. Edit the configuration file on the Dundas Dashboard server.
  3. Uncomment the defaultCulture element and change its value from Auto to fr-FR, which is the French (France) culture.
  4. Restart the Dundas Dashboard website for the changes to take effect.

Finally, view the dashboard from the viewer:

  1. Open a web browser and navigate to the dashboard viewer URL, which looks something like http://mydashsvr/Viewer.aspx or http://mydashsvr:7000/Viewer.aspx.
  2. Log in to the viewer.
  3. Locate the New Dashboard icon in the viewer's navigation bar and double-click to view it.
  4. Observe that the date label on the dashboard is now displayed according to the new culture which was set via the configuration file.
    Date displayed with new default culture.

Currency formats

Continuing with the previous example, suppose you have an existing dashboard which displays figures in US dollars, but you used currency formats such as “C” or “C0” to format your axis labels. Once the default culture is switched to French (France), this dashboard not only displays dates in French, but it also displays currencies in Euros, which is now misleading as the actual currency values have not changed.

A sales dashboard is displayed using the French (France) culture.

A sales dashboard is displayed using the French (France) culture.


The key point here is that using currency formats such as “C” in your dashboards should be avoided. Instead, hard-code the applicable currency symbol directly into your format strings so that it remains invariant under culture changes.

Changing the default culture for a user

The Dundas Dashboard administrator can set the default culture for each user account. This setting can be used to override the default culture of the application.

To view or change the default culture for a specific user:

  1. Log in to Dundas Dashboard as an administrator.
  2. Go to the Administration sidebar.
  3. Edit the desired user account.
  4. In the General tab, locate the Language dropdown list and set it to the desired culture. Observe that there is always one entry which is prefixed with Default. Setting the dropdown to this item implies that you want to use the default culture of the application (which is determined by the configuration file as shown previously).

Setting the default language/culture for a user account.

Setting the default language/culture for a user account.


Note: The number of choices in the Language dropdown list is determined by the number of extra languages (translations) that are actually installed on your Dundas Dashboard instance.

Adding a new language

This section shows how to add support for a new language/culture to Dundas Dashboard. Once added, the new language will appear as an option in:

  • The Language dropdown list in the General tab of the Editing Account screen, which determines the default language for each user.
  • The Language dropdown list in the dashboard viewer's login screen, which allows the users of your dashboards to choose the language they want to use when viewing dashboards.

Folder structure

Language localization (XML) files are located under the App_Data\Localization folder of your Dundas Dashboard instance. By default, this folder path is:

C:\Program Files\Dundas Data Visualization Inc\Dundas Dashboard\{InstanceName}\www\App_Data\Localization

The App_Data\Localization folder.

The App_Data\Localization folder.


The XML files are placed in sub-folders according to the different application areas such as Client and Server. For example, the default or base language localization file in the App_Data\Localization\Client folder is: Client.base.xml. Plugins also have their own localization files.

The App_Data\Localization\Client folder.

The App_Data\Localization\Client folder.


Localization XML file

A language localization file is an XML document with the following basic structure:

<?xml version="1.0" encoding="utf-8" ?>
<localization>
  <group>
    <string></string>
    ... more strings ...
    ... more groups ...
  </group>
</localization>

The default localization files that are included with the Dundas Dashboard installation use the word base in their filenames. For example:

  • Client.base.xml
  • Common.base.xml
  • Server.base.xml

Non-default (i.e. new) localization files are named similarly, but substitute the word base with the corresponding culture name. For example:

  • Client.fr.xml
  • Client.fr-FR.xml
  • Client.fr-CA.xml

Element: localization

The localization element specifies the culture and the version number of the localization file. Only one localization element is permitted per localization file.

For default localization files, the culture attribute is set to: x-base. Example:

... one or more groups ...

For non-default (i.e. new) localization files, the culture attribute should be set to the corresponding culture name, such as fr or de-DE. Example:

... one or more groups ...

Element: group

The group element is used to group related translation strings. Groups can be nested within another group.

Most of the strings that are displayed in the dashboard viewer are listed in the Client.base.xml file under the group named Viewer.

Example:

... one or more strings ...

Element: string

The string element is used to specify the translated text for a string that appears in the application's user interface. The key attribute uniquely identifies the string and must not be changed. The actual translated text appears between the start and end tags of the string element.

Example:

<string key="GS_CTL_VWR_BookmarkCreated">The bookmark was successfully created</string>

Example: Localizing the Logout button

This example shows how to add support for the French (France) language/culture by localizing the text of the Logout button in the dashboard viewer's toolbar.

Assuming that you have a default installation of Dundas Dashboard (in terms of language support):

  1. On the Dundas Dashboard server, go to the App_Data\Localization\Common folder.
  2. Make a copy of the Common.base.xml file and place it in the same folder. This localization file contains the string element that corresponds to the text of the Logout button.
  3. Rename the copied file to: Common.fr-FR.xml
  4. Edit the new file in a text editor and find the localization element at the top of the file. Change the culture attribute from x-base to fr-FR, which represents French (France).
  5. Also locate the string element with the key GS_CTL_VWR_ToolbarLogout. This will be near the end of the file.
  6. Replace the text Logout with Déconnexion.
    <string key="GS_CTL_VWR_ToolbarLogout">Déconnexion</string>
  7. Save your changes to the new localization file.
  8. Restart the Dundas Dashboard website for the changes to take effect.

Next, log in to Dundas Dashboard as an administrator:

  1. Go to the Administration sidebar.
  2. Edit a user account.
  3. Click the Language dropdown list and observe that French (France) has been added as an available culture. Set the language to this culture and save the user account changes.
  4. Log out of Dundas Dashboard.
    The Editing Account screen with French option.

Finally, open a browser window and navigate to the Viewer.aspx URL:

  1. The viewer login screen now has a Language dropdown list, which lets you choose an available language. Leave it set to default, which means that the default language for the user account will be used (i.e. as per the setting in the Editing Account screen).
    The viewer login screen.
  2. Enter the credentials of the user account which was previously modified and click Login.
  3. Observe that the text of the Logout button is now displayed according to the text in the Common.fr-FR.xml localization file.
    Logout button in French.

Tip: You can also force the dashboard viewer to use a specific culture by passing in the ddCulture query parameter when you navigate to the Viewer.aspx URL. For example: http://mydashsvr/Viewer.aspx?ddCulture=fr-FR

Notes

Fallback mechanism

Localization files work under a convenient fallback mechanism such that if Dundas Dashboard cannot locate a specific string in a file, it will look for the string in its immediate ancestor. This means that when copying a localization file in order to prepare a new translation, it is not necessary to include all of the original strings in the translated file. You only need to include the strings that will actually be translated. For example, in the Logout button example, we could have placed just a single string element for the GS_CTL_VWR_ToolbarLogout key in the Common.fr-FR.xml file.

The fallback mechanism works by looking for strings in the most specific (in terms of culture name) localization file first. Here is an example priority list:

  1. Client.fr-FR.xml
  2. Client.fr.xml
  3. Client.base.xml

In this case, if a string cannot be found in Client.fr-FR.xml, Dundas Dashboard looks in the Client.fr.xml file next, followed by Client.base.xml.

Upgrading to a new Dundas Dashboard version

When upgrading to a new Dundas Dashboard version, note that localization strings may be added or removed from localization files between one version and the next. Thus, if you have made your own custom translations, you should review the localization files for differences after upgrading.

Default.aspx

If you are accessing Dundas Dashboard via the regular/full application URL (e.g. Default.aspx), your default culture will be applied when you preview or view dashboards only if that culture is for the English language. For example, the culture must be one of en-US, en-GB, en-CA, etc. If your default culture is non-English, dashboard viewing and previewing will revert to using en-US.

Setting the culture for a Windows Group account

When Dundas Dashboard is configured to use Windows authentication, and a Windows user logs in but no language (culture) is associated with the user's account, Dundas Dashboard will check each of the Windows Group accounts that the user belongs to and use the language/culture that is specified by one of the groups (generally the first group that has a language/culture defined).

Localizing parameter tokens

Token captions (such as All values) for parameter controls such as the Hierarchy viewer can be localized during setup of the parameter at design-time. In particular, for parameter controls that are OLAP-sourced, this is the only way currently for designers to localize token captions.

Administrators can localize both custom and built-in tokens using the Token Designer.

Related topics


Click to return to: Documentation

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.