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

image from book
  <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> 
image from book

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

image from book
 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 
image from book




Professional DotNetNuke 4.0 (c) Open Source Web Application Framework for ASP. NET 4.0
Professional DotNetNuke 4: Open Source Web Application Framework for ASP.NET 2.0 (Programmer to Programmer)
ISBN: 0471788163
EAN: 2147483647
Year: 2006
Pages: 182

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net