Summary

Language Add-Ons

Support for multiple languages was added in DotNetNuke 3.0. The DotNetNuke implementation loosely follows the localization architecture and naming conventions of the ASP.NET 2.0 framework. DotNetNuke 4.0 recognizes language add-ons for the core framework, modules, providers, and a full language pack, including resources for both the core framework and all installed modules and providers. The only difference between the various language pack types are the specific string resource files included.

The multi-language architecture poses a unique challenge for creating and installing Language Packs due to the number of directories and files involved. Like code add-ons, Language Packs utilize a manifest file to manage the metadata necessary to get all of the files installed to the correct directory.

Language Pack Manifest File

The Language Pack manifest file follows a very simple format, as shown in Listing 17-7.

Listing 17-7: Language Pack Manifest File Format

 <?xml version="1.0"?> <LanguagePack xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="3.0">   <Culture Code="" DisplayName="" />   <Files>     <File FileName="" FileType="" ModuleName="" FilePath=""/>   </Files> </LanguagePack> 

This file relies on the use of attributes, which is a more compact format than using simple elements. Table 17-11 lists the file's key elements.

Table 17-11: Manifest File Elements

Element	Description
LanguagePack	The root element for the manifest file. It must be created exactly as shown in Listing 17-7. The installation code will validate the file against the listed schemas.
Culture	Defines the culture information associated with the current Language Pack. The Culture contains two attributes: Code and DisplayName. The Code attribute takes a value corresponding to a valid culture name as defined by the .NET Framework System.Globalization.CultureInfo class. DisplayName defines the name to display when languages are selected in the portal framework.
Files	Contains one or more File nodes that provide the information necessary to properly install the individual resource file identified by the File node. See Table 17-10 for more information about the individual attributes of the File element.

Each language resource included in the Language Pack must be identified by a corresponding file element in the manifest (see Table 17-12). The files will be saved based on predefined rules depending on the file type.

Table 17-12: Manifest File Elements

Attribute	Description	Required
FileName	Defines the name of the physical file. It should not include any path information.	Yes
FileType	Defines the type of file identified by this node and is used by the portal to determine the root directory where the file will be installed. The FileType must be one of four values: GlobalResource, AdminResource, ControlResource, or LocalResource. See Table 17-11 for more information on these i file types.	Yes
ModuleName	Required for files marked AdminResource or LocalResource. This value identifies the name of the Admin or Desktop module that is associated with this file. ModuleName is the same as the name of the directory name in which the module is installed.	No
FilePath	Defines a path relative to the default resource path. The file path where the file will be saved is: [RootPath]\[ModuleName]\[FilePath]\[ResourceDirectory]. The RootPath and ResourceDirectory values are determined by the file type and are i defined in Table 17-11.	No

The FileType attribute is used to determine the appropriate RootPath and Resource directory (see Table 17-13). The RootPath value corresponds to specific directories defined by DotNetNuke. Admin modules, controls, and Desktop modules are the only DotNetNuke elements that are permitted to have local language resources. All other elements should use the Global resources. The Resource directory is defined to correspond to ASP.NET 2.0.

Table 17-13: FileType Values

FileType	Description	RootPath	Resource Directory
GlobalResource	Shared resources	\	App_GlobalResources
AdminResource	Admin module resources	\admin	App_LocalResources
ControlResource	Control resources	\controls	App_LocalResources
LocalResource	Desktop module resources	\Desktopmodules	App_LocalResources

To simplify the creation of the manifest file, DotNetNuke includes the capability to generate the Language Pack to include the manifest file. Although the manifest file may be hard to maintain by hand, it is a format that lends itself well to automatic generation and is easily read during the installation process. Listing 17-8 shows a partial listing of the generated Deutsch (German) manifest file.

Listing 17-8: German Language Pack Manifest

 <?xml version="1.0"?> <LanguagePack xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="3.0">   <Culture Code="de-DE" DisplayName="Deutsch" />   <Files>     <File FileName="GlobalResources.de-DE.resx" FileType="GlobalResource" />     <File FileName="SharedResources.de-DE.resx" FileType="GlobalResource" />     <File FileName="TimeZones.de-DE.xml" FileType="GlobalResource" />     <File FileName="Announcements.ascx.de-DE.resx" FileType="LocalResource" ModuleName="Announcements" />     <File FileName="EditAnnouncements.ascx.de-DE.resx" FileType="LocalResource" ModuleName="Announcements" /> ... ... ... ... ... ...     <File FileName="Address.ascx.de-DE.resx" FileType="ControlResource" />     <File FileName="DualListControl.ascx.de-DE.resx" FileType="ControlResource" />     ...     ...     <File FileName="Classic.ascx.de-DE.resx" FileType="AdminResource" ModuleName="ControlPanel" />     <File FileName="IconBar.ascx.de-DE.resx" FileType="AdminResource" ModuleName="ControlPanel" />     ...     ...   </Files> </LanguagePack> 

Packaging Language Packs

A Language Pack includes three different types of files:

• Language resource: A language resource file is a standard .NET resource file that includes a key name and the localized value. A call to the DotNetNuke method GetString(key) returns the value that corresponds to the key.

• Time zones: The TimeZones.[locale].xml file includes a list of time zones that are recognized by the DotNetNuke portal.

• Manifest: The manifest file identifies the resource files included in the Language Pack.

DotNetNuke includes the capability to generate Language Packs for any of the languages and cultures that are currently installed on your portal. Given the number of files and directories involved in putting together a complete Language Pack, the generator is the recommended method for creating it. Not only does the generator simplify the creation process, but it also ensures that all necessary files are included and that the manifest file is properly formatted. Follow these simple steps to create a Language Pack.

1. Log in with the Host account and go to the Languages page on the Host menu (see Figure 17-15). Although the Admin account has some capability to edit language resources, it does not have the necessary permissions to generate or import Language Packs.

2. The Languages screen provides a number of options for adding new locales and languages to your portal. If you want to generate a Language Pack for a language that does not appear in the Supported Locales list, you must first add the language to your portal. (See Chapter 5 for more information about adding languages.) Select Create Language Pack from the Action menu or from the links at the bottom of the screen as shown in Figure 17-16.

3. The latest versions of DotNetNuke enable you to create language packs for different subsets of the installed localized resources. (Earlier versions required you to create a Language Pack that included all localized strings. This behavior would include module strings that could cause problems for users who do not have the same modules in their installation.) As shown in Figures 17-17 through 17-20, each resource pack type provides specific options to customize the resource pack name and to select the resources that will be included in the package. For this example, select Full as the Resource Pack Type and then select the locale for which you want to create a Language Pack. Click the Create link (see Figure 17-20) to generate the Language Pack after you've made your selections.

4. After the Language Pack is created, you are presented with a complete log showing all of the files added to the Language Pack (see Figure 17-21). Review the logs for errors, which are highlighted in red. Additionally, the log shows you important information about the directory in which the generated Language Pack is stored. The log also provides a link to the File Manager so that you can download the Language Pack from the portal server.

Figure 17-15

Figure 17-16

Figure 17-17

Figure 17-18

Figure 17-19

Figure 17-20

Figure 17-21

Installing Language Packs

Just like code and skinning add-ons, Language Packs also support two installation methods: web-based and FTP-based. Language Packs can include hundreds of files, which must be properly referenced in the manifest file. Any mismatch between the files identified in the manifest and files included in the Language Pack results in an error. Additionally, the manifest file controls where each resource will be installed. An error in the manifest could result in a resource file being installed into the wrong directory. If you use the DotNetNuke Language Pack Generator to create the Language Pack, the likelihood of errors during installation is significantly reduced.

Web-Based File Upload

Follow these four steps to install a new language into your portal using the web-based installer:

1. Log in with the Host account and go to the Languages page on the Host menu (shown previously in Figure 17-15). Although the Admin account has some capability to edit language resources, it does not have the necessary permissions to generate or import Language Packs.

2. The Languages screen provides a number of options for new locales and languages. If you want to generate a Language Pack for a language that does not appear in the Supported Locales list, you must first add the language to your portal. (See Chapter 5 for more information about adding additional languages.) Select Upload Language Pack from the Action menu or from the links at the bottom of the screen (see Figure 17-22).

3. The File Upload screen appears (see Figure 17-23). Select the file you want to upload and ] the Upload New File link.

4. After the Language Pack is uploaded, you are presented with another File Upload screen. This screen displays the complete Resource Upload Logs showing all of the files that have been uploaded (see Figure 17-24). Review the logs for errors, which are highlighted in red. Additionally, the log shows you important information about the directory where the generated Language Pack is stored, and the log provides a link to the File Manager so that you can download the Language Pack from the portal server.

Figure 17-22

Figure 17-23

Figure 17-24

FTP-Based Installation

To install a new Language Pack using FTP or any file manager, copy the Language Pack into the Install/Language directory of your DotNetNuke installation. When the ResourceInstaller task runs, it will install the Language Pack using the standard skin installation code. If an error occurs, it's noted in the task history, which is available by selecting the History link for the ResourceInstaller task on the Schedule page (shown previously in Figure 17-7).