Localizing Modules

The API

The DotNetNuke.Services.Localization.Localization class provides the methods necessary for localizing strings. These methods are described in Table 11-1.

Table 11-1: Localization Methods

Method	Description
AddLocale	Used to add a locale to the list of supported locales in the App_GlobalResources/Locales.xml file.
GetResourceFile	Returns the path and filename of the resource file for a specified control.
GetString	Returns the localized string based on the resource key specified.
GetSupportedLocales	Returns the list locales from the App_GlobalResources/Locales .xml file.
GetSystemMessage	Localizes a string and replaces system tokens with personalized strings.
GetTimeZones	Returns a key/value pair collection of time zones.
LoadCultureDropDownList	Fills a DropDownList control with the supported cultures.
LoadTimeZoneDropDownList	Fills a DropDownList control with the list of time zones.
LocalizeDataGrid	Localizes the headers in a DataGrid control.
LocalizeRole	Localizes the three system roles.

The GetString Method

Of the methods in Table 11-1, the most widely used is GetString. It performs localization based on the resource key passed into it. GetString has five overloaded methods, detailed here:

• To localize a string value that has a translation in an Application Resource file, use the following method:

   Public Shared Function GetString(ByVal name As String) As String 

  The resource file to be used will be selected based on the currently active locale. This automatically uses the active PortalSettings object to derive the portal's default locale.

  Parameter	Type	Description
  name	String	The string to be localized.

• The following is identical to the previous method, except you can send in a PortalSettings object to derive the portal's default locale:

   Public Shared Function GetString(ByVal name As String, ByVal objPortalSettings _ As PortalSettings) As String 

  Parameter	Type	Description
  name	String	The string to be translated.
  objPortalSettings	PortalSettings	The PortalSettings object for the current context. It determines the default locale used for anonymous users.

• To localize a string value that has a translation in a Local Resource file, use the following method:

   Public Shared Function GetString(ByVal name As String, ByVal ResourceFileRoot _ As String) As String 

  The following method accepts an incoming parameter (ResourceFileRoot) from which the resource file to use is derived. It automatically uses the active PortalSettings object to derive the portal's default locale.

  Parameter	Type	Description
  name	String	This is the string to be translated.
  ResourceFileRoot	String	This is the value of a module's LocalResourceFile property. It is used to derive the resource file to be used for the translation

• The following method enables you to specify the key name to translate, and both the resource file and portal settings to use for the translation:

   Public Shared Function GetString(ByVal name As String, ByVal ResourceFileRoot _ As String, ByVal strLanguage As String) As String 

  Parameter	Type	Description
  name	String	The string to be translated.
  ResourceFileRoot	String	The value of a module's LocalResourceFile property. It is used to derive the resource file to be used for the translation.
  strLanguage	String	The name of the language used to look up the string.

• The following method enables you to specify the key name to translate, and both the resource file and portal settings to use for the translation:

   Public Shared Function GetString(ByVal name As String, ByVal ResourceFileRoot _ As String, ByVal objPortalSettings As PortalSettings, ByVal strLanguage _ As String) As String 

  Parameter	Type	Description
  name	String	The string to be translated.
  ResourceFileRoot	String	The value of a module's LocalResourceFile property. It is used to derive the resource file to be used for the translation.
  objPortalSettings	PortalSettings	The PortalSettings object for the current context. If the localized string does not exist for the given language, then the default locale specified in objPortalSettings is used.
  strLanguage	String	The name of the language used to look up the string.

The GetSystemMessage Method

The GetSystemMessage method is used throughout the core code to produce localized and personalized strings. For example, it is used frequently to send e-mail to registered users. The user registration page calls GetSystemMessage to localize the content of the e-mail that gets sent to the user. The e-mail contains personalized content, too, so rather than concatenating several dozen strings using the GetString method and wrapping them around personalized data, GetSystemMessage takes care of all of this with just one call.

GetSystemMessage has eight overloaded methods, described here:

• Use the following method if you need to localize and personalize a string when the personalization can be derived from the objPortal property. The translation must be stored in the Application Resources file.

   Public Shared Function GetSystemMessage(ByVal objPortal As PortalSettings, _ ByVal MessageName As String) As String 

  Parameter	Type	Description
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file. Because no user information is included in this overload, "User:" MessageName types are not supported.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from either the objPortal or objUser properties. The translation must be stored in the Application Resource file.

   Public Shared Function GetSystemMessage(ByVal objPortal As PortalSettings, _ ByVal MessageName As String, ByVal objUser As UserInfo) As String 

  Parameter	Type	Description
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file.
  objUser	UserInfo	The UserInfo object to derive any personalized content within the localized system message string.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from the objPortal or objUser object's properties. You must specify the language to use for the translation, and the translation must be stored in the Application Resource file.

   Public Shared Function GetSystemMessage(ByVal strLanguage As String , _ ByVal objPortal As PortalSettings, ByVal MessageName As String, _ ByVal objUser As UserInfo) As String 

  Parameter	Type	Description
  strLanguage	String	The name of the language used to look up the string.
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file.
  objUser	UserInfo	The UserInfo object to derive any personalized content within the localized system message string.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from the objPortal property values. You must specify the resource file to use for the translation.

   Public Shared Function GetSystemMessage(ByVal objPortal As PortalSettings, _ ByVal MessageName As String, ByVal ResourceFile As String) As String 

  Parameter	Type	Description
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file.
  ResourceFile	String	The resource file that the localized system message is stored in.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from either the objPortal or objUser properties. You must specify the resource file from which to retrieve the translation.

   Public Shared Function GetSystemMessage(ByVal objPortal As PortalSettings, _ ByVal MessageName As String, ByVal objUser As UserInfo, ByVal ResourceFile _ As String) As String 

  Parameter	Type	Description
  objPortal	PortalSettings	This is the PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	This is the resource key used to get the localized system message from the resource file.
  objUser	UserInfo	This is the UserInfo object to derive any personalized content within the localized system message string.
  ResourceFile	String	This is the resource file that the localized system message is stored in. It is usually the value of the module's LocalResource File property.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from the objPortal object's properties and the Custom ArrayList collection items. You must specify the resource file to use for the translation.

   Public Shared Function GetSystemMessage(ByVal objPortal As PortalSettings, _ ByVal MessageName As String, ByVal ResourceFile As String, ByVal Custom As _ ArrayList) As String 

  Parameter	Type	Description
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file.
  ResourceFile	String	The resource file that the localized system message is stored in.
  Custom	ArrayList	A collection of strings that can be used for personalizing the system message.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from objPortal, the objUser properties, and the Custom ArrayList collection items. You must specify the resource file from which to retrieve the translation.

   Public Shared Function GetSystemMessage(ByVal objPortal As PortalSettings, _ ByVal MessageName As String, ByVal objUser As UserInfo, ByVal ResourceFile As _ String, ByVal Custom As ArrayList) As String 

  Parameter	Type	Description
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file.
  objUser	UserInfo	The UserInfo object to derive any personalized content within the localized system message string.
  ResourceFile	String	The resource file that the localized system message is stored in. It is usually the value of the module's LocalResourceFile property.
  Custom	ArrayList	A collection of strings that can be used for personalizing the system message.

• Use the following method if you need to localize and personalize a string when the personalization can be derived from the objPortal object's properties and the Custom ArrayList collection items. Also, you must specify the resource file and the language to use for the translation.

   Public Shared Function GetSystemMessage(ByVal strLanguage As String, _ ByVal objPortal As PortalSettings, ByVal MessageName As String, _ ByVal objUser As UserInfo, ByVal ResourceFile As String, _ ByVal Custom As ArrayList) As String 

  Parameter	Type	Description
  strLanguage	String	The name of the language used to look up the string.
  objPortal	PortalSettings	The PortalSettings object for the current context. It is used to derive any personalized content within the localized system message string.
  MessageName	String	The resource key used to get the localized system message from the resource file.
  objUser	UserInfo	The UserInfo object to derive any personalized content within the localized system message string.
  ResourceFile	String	The resource file that the localized system message is stored in. It is usually the value of the module's LocalResourceFile property.
  Custom	ArrayList	A collection of strings that can be used for personalizing the system message.

When you use GetSystemMessage, you can specify several system tokens in the localized string. The tokens are used as keys to render property values from either the UserInfo or PortalSettings objects. Here's an example:

 DotNetNuke.Services.Localization.Localization.GetSystemMessage(PortalSettings, _ "EMAIL_USER_REGISTRATION_PRIVATE_BODY", objNewUser, Me.LocalResourceFile) 

This code calls the GetSystemMessage method to localize and personalize the body of an e-mail message that is sent to a newly registered user. The code is found in the Admin/Security/Register.ascx portal module. The MessageName parameter value is EMAIL_USER_REGISTRATION_PRIVATE_BODY. It is the resource key to look up the system message in the resource file. The resource key and associated translation from the resource file /Admin/Security/App_LocalResources/Register.ascx.resx is shown in Listing 11-1.

Listing 11-1: System Message Resource Example

  <data name="EMAIL_USER_REGISTRATION_PRIVATE_BODY.Text">      <value>          Dear [User:FullName], Thank you for registering at the [Portal:PortalName] portal website. Please read the following information carefully and be sure to save this message in a safe location for future reference. Portal Website Address: [Portal:URL] Username: [Membership:UserName] Password: [Membership:Password] Your account details will be reviewed by the portal Administrator and you will receive a notification upon account activation. Thank you, we appreciate your support... [Portal:PortalName]      </value>  </data> 

GetSystemMessage first localizes the string within the <value> XML node. Then it iterates through the system tokens (enclosed in brackets), replacing the tokens with the appropriate property values. For example, in Listing 11-1 you can see the token [User:FullName]. This will be replaced with the FullName property value of the User object. In this case, the User object is the objUser object passed into the GetSystemMessage method. Listing 11-2 shows that the system message has been personalized and localized with the en-US locale.

Listing 11-2: System Message Rendered Example

 Dear John Doe, Thank you for registering at the DotNetNuke portal website. Please read the following information carefully and be sure to save this message in a safe location for future reference. Portal Website Address: http://test.dotnetnuke.com Username: jdoe1234 Password: pwdjdoe1234 Your account details will be reviewed by the portal Administrator and you will receive a notification upon account activation. Thank you, we appreciate your support... DotNetNuke