The API

Overview

The localization API in DotNetNuke provides developers with an interface for performing multilingual translations in custom portal modules. As of this writing, DotNetNuke includes only static localization features. In other words, only text labels and other static strings are localized by the core.

Dynamic content localization is a feature that is closely related to content versioning. In traditional versioning systems, content changes along a single axis represented by time. By extending your view of versioning to include a second axis based on culture, you can overcome many of the challenges of dynamic content localization. This approach to dynamic localization will be addressed in a future DotNetNuke release.

Locales

A locale is the combination of a country code and a language code. For the sake of accurate translations, it is important to use both a country code and a language code to perform localization. Many languages are spoken in more than one country, and dialects may differ from country to country. For instance, French spoken in Canada is different from French spoken in France. A locale accounts for this differentiation. DotNetNuke supports four types of locales:

• System locale: The locale (en-US) that DotNetNuke is natively coded. It cannot be changed.

• Default portal locale: The portal's default locale, which is specified in the Site Settings screen (see Chapter 5). This locale will be automatically selected for any users who have not yet defined their default locale.

• User-selected locale: The locale that a user selects from the Registration or User Account page.

• Custom locale: A custom locale allows for customized translations to be defined for each portal. The localization framework manages this by appending the PortalID onto the locale. For instance, if Portal 2 has configured custom German translations, the custom locale for de-DE for Portal 2 is de-DE.Portal-2.

Resource Files

To align closely to the ASP.NET 2.0 localization implementation, DotNetNuke uses the Windows Resource Files (RESX) format to store translations. This file format uses XML tags to store key/value pairs of string values. Developers often use the Template.resx file in the root App_Resources directory as a starting place to create their resource files.

Here's an example of the Data Provider form field on the Host Settings page that shows the format of a resource file's data elements:

 . . .        <data name="plDataProvider.Text">             <value>Data Provider:</value>       </data>       <data name="plDataProvider.Help">             <value>The provider name which is identified as the default data provider in the web.config file</value>       </data> . . . 

Each name attribute is referred to as a resource key. Notice that the two resource keys in this example have extensions. DotNetNuke uses a number of extensions that help identify translations more easily:

• .Text: Used for the text properties of controls (default if not included in resource key).

• .Help: Used for help text.

• .Header: Used for the HeaderText properties of DataGrid columns.

• .EditText: Used for the EditText properties of DataGrids.

• .ErrorMessage: Used for the ErrorMessage property of Validator controls.

There are three types of static translations in DotNetNuke: Application Resources, Local Resources, and Global Resources. These static translations are defined in the following sections.

Application Resources

Application Resources translations are shared throughout many controls in DotNetNuke. Application Resources files are the storage area for generic translations. For example, to localize the words "True" and "False," you would store the translations in the Application Resources files. Other examples of Application Resources are Yes, No, Submit, and Continue.

Application Resources are stored in the App_GlobalResources directory, which is directly under the DotNetNuke root installation directory. The filename for the system locale (en-US) for Application Resources is SharedResources.resx. The file naming convention for other locales is SharedResources.[locale].resx. For example, the German Application Resource file would be named SharedResources.de-DE.resx.

Local Resources

Local Resources translations are unique to a user control. For example, to localize the Announcements module's user control, you would store the translations in a Local Resources file that lives in a child directory beneath the Announcements module's directory.

Note 

If the Announcements module has static translations that are generic in nature (such as True and False), the translations should be gathered from Application Resources.

Local Resources files are stored in a directory named App_LocalResources. Each directory that contains localized user controls must have a directory named App_LocalResources. The filename for the System Locale follows this naming convention:

 [control_directory]/App_LocalResources/[user_control_file_name].resx. 

For example, for the en-US locale, the resource file for the Announcements module would be as follows:

 Announcements/App_LocalResources/Announcements.ascx.resx. 

The filename for other locales follows this naming convention:

 [control_directory]/App_LocalResources/[control_files_name].[locale].resx. 

Global Resources

Global Resources translations are for localizing strings from components that do not have Local Resource files, are not necessarily shared translations, and don't fit in the first two categories. Because all Local Resources are associated with a user control or a page, there is no place to store translations for components. For this reason, there's now this third category for resource files. An example of Global Resources usage is in the component admin/Containers/ActionBase.vb, which needs to localize the word Help in the module action lists.

Global Resources are stored in the same directory as Application Resources (/App_Resources). The file name for the system default locale is /App_Resources/GlobalResources.resx. For locales other than the system default, the naming convention is as follows:

 /App_Resources/GlobalResources.[locale].resx