Building Microsoft ASP.NET Applications for Mobile Devices, Second Edition [Electronic resources] نسخه متنی

Creating and Using Resource Files

Any application displays a lot of text. Not only is there the text that you define in Label and TextView controls, there's also many other properties of mobile controls that display text to the user, such as page headings, navigation prompts to move forward or backward through the application, menu links, and so on. The following are some of the most common sources of text in any application:

You set static text displayed in the Label and TextView controls at run time by using the Text property.

The Title property of the Form control displays on the head of a page in many browsers.

When you enable a Form control for pagination, you set the text displayed for the forward and backward links through the NextPageText and PreviousPageText properties of that control's PagerStyle object.

Various controls contain properties you can display only on a specific type of device. An example of this is the SoftkeyLabel property of the Link and Command controls.

You use the Text property of the MobileListItem object to display static text in a listing using the SelectionList and List controls.

When displaying a list of data objects using the ObjectList control, the column heading that displays for data fields is defined by the Title property of the ObjectListField object.

You set the menu prompt for an ObjectList item command using the Text property of an ObjectListCommand object.

You use the MoreText property of the ObjectList control to set the text displayed for the link used to view the details of an item.

The normal way to set these strings (and the method used by 99 percent of the examples in this book) is simply to use the properties window of the Mobile Internet Designer to set the properties of mobile controls that take textual values, or to set properties in code using embedded literal strings. That's fine if you're supporting only a single culture in your application, but if you're producing internationalized applications, you should separate the definition of strings from the code, and store all string definitions in resource files.

As we described in the previous section, you set the UICulture property at run time to define which resource file should be used to provide the string values to be used with the current request. For example, if you want your application to support localized content for English, French, and French-Canadian, you'd set the UICulture property to a CultureInfo object for the requested language, en, fr, or fr-CA when a request comes in from a client requesting one of those languages. Then in code you use a System.Resources.ResourceManager object to fetch strings from the selected resource file.

Microsoft Visual Studio .NET makes adding resource files easy. As a simple exercise, create a mobile application that has a single Form control on it as well as three Label controls. Figure 14-1 shows how this application might appear in the Mobile Internet Designer.

Figure 14-1: Form to be localized

In this example, you'll provide translations in English, German, and French, identified by the UICulture settings of en, de, and fr, respectively. In fact, we won't create a Resources.en.resources file for the English language because we will place English translations into the default (invariant) culture resources file, Resources.resx.

One of the great things about the way that resource files are managed in .NET is that you can add support for new languages later on, without recompiling the main application. If you set the UICulture property to a particular culture, and at run time no resource file for that culture is found, the client just gets the string resources defined for the invariant culture. You can deploy a resource assembly for a new culture later on, and the application will start to use it without having to recompile the application. See the sidebar "Resource Manager and Satellite Assemblies" for a more detailed explanation of how the .NET Resource Manager uses resources at run time. You have to define string resources in the invariant culture resources file using one language or another; in this application, the language used is English.

To create a resources file in Visual Studio.NET, right-click the project in Solution Explorer, point to Add, and then click Add New Item. In the Add New Item window, scroll down the Templates pane, select Assembly Resource File, and give it a suitable name, such as MyResources.resx. This first resource file is for the neutral culture, and this application uses this file for any clients that don't specify a preference for French or German.

The XML Designer allows you to create strings in the resource file, add a comment to them, and identify those strings with a name. You must add the text to be displayed on each of the three controls on the mobile Web Forms page, as Figure 14-2 shows.

Figure 14-2: Defining strings for localization using the Visual Studio .NET Resource Editor

.NET resource files are compiled into special assemblies known as satellite assemblies. Satellite assemblies contain only resources and no executable code. These assemblies have a number of advantages. The most important advantage is that satellite assemblies allow you to deploy resources for a new language separately from the main application so that you can update resources or add support for new languages without the need to recompile and distribute your entire application. Another benefit is that a satellite assembly is a dynamic-link library (DLL) which is shadow-copied by each process that accesses it, meaning that you can update the satellite assembly even if it's in use.

Resources for the default culture are compiled into the main application assembly. Resources for other cultures are compiled into a satellite assembly and deployed in a directory beneath the \bin folder in your application that has the name of the culture code. For example, default culture resources for the application LocalizingExample go into \bin\LocalizingExample.dll, French resources into \bin\fr\LocalizingExample.resources.dll, and German resources go into \bin\de\LocalizingExample.resources.dll. If you use Visual Studio .NET to build your applications, it does so without your having to take any special steps.

If you set the culture at run time to a particular locale code and the Resources Manager can't find a satellite assembly containing resources for that locale, the resources in the default culture resources file (which are in English in this application) are used. You can use this behavior to release an application that initially supports only one or a few cultures and then add support for more cultures without having to recode your main application. Even if

setCulture sets the

Culture and

UICulture properties of the application to a culture for which no resources are found at run time, the client will get the default culture. But if you create the resources file for a culture later and compile it, you can just deploy the satellite assembly for that culture onto the Web server, and the application will automatically start using it.

If you are deploying satellite assemblies later, you do have to make sure that the satellite assembly has the same version number as the main assembly. See Chapter 17 for details of how to set the version number of an assembly.

Create two more assembly resource files with the same prefix, MyResources, but ending with .de.resx for the German translation and .fr.resx for the French version. In the Resource Editor, add entries for the three strings using the same name as you did for the English version.

When you compile this application, it creates a satellite DLL named projectName.resources.DLL in a subdirectory under the /bin directory for each of the culture-specific resource files you've created. In other words, the German resources reside in /bin/de, and the French reside in /bin/fr. The default culture resources (in this case, the English version) reside in the main application assembly in /bin.

Create a ResourceManager object which you use to access these resources at run time using the name you gave to each resource string. The form of the constructor you'll want to use takes two parameters, as shown here:

  ResourceManager  LocRM = 
new ResourceManager("MSPress.MobWeb.LocalizingEx.MyResources",
typeof(MobileWebForm1).Module.Assembly);

The first parameter is the root name of the resources. For example, the root name for the resource file named "MyResource.en-US.resources" is "MyResource". You should prefix this with the namespace name, as previously shown.

The second parameter is the main assembly for the resources.

Once you have a ResourceManager, use the GetString("resource_string_name") method to fetch strings from the resource file:

  Label1.Text = LocRM.GetString("Title");

The ResourceManager uses the current UICulture setting to determine which resource assembly to access. For example, this application uses the setCulture method shown in Listing 14-1 to define the Culture and UICulture properties and then creates a ResourceManager object to set the strings, as Listing 14-2 shows. This example also uses the DateTime.Now.ToString method to return the LongDateTimeFormat (format identifier F). This identifier formats the date in the appropriate language and layout as defined in the current Culture setting.

Listing 14-2: Code-behind file Default.aspx.cs of the LocalizingExample project demonstrates using localized string resources.

using System;
using System.Web.UI.MobileControls;
using System.Resources;
using System.Threading;
using System.Globalization;
namespace MSPress.MobWeb.LocalizingEx
{
public class MobileWebForm1 : System.Web.UI.MobileControls.MobilePage
{
protected System.Web.UI.MobileControls.Label Label1;
protected System.Web.UI.MobileControls.Label Label2;
protected System.Web.UI.MobileControls.Form Form1;
protected System.Web.UI.MobileControls.Label Label3;
protected ResourceManager LocRM;
override protected void OnInit(EventArgs e)
{
InitializeComponent();
base.OnInit(e);
}
private void InitializeComponent()
{
this.Load += new System.EventHandler(this.Page_Load);
}
private void Page_Load(object sender, System.EventArgs e)
{
setCulture();
LocRM = new ResourceManager(
"MSPress.MobWeb.LocalizingEx.MyResources",
typeof(MobileWebForm1).Module.Assembly);
Label1.Text = LocRM.GetString("Title");
Label2.Text = LocRM.GetString("Message");
Label3.Text = LocRM.GetString("DateTimelegend") + ": " +
DateTime.Now.ToString("F");
}
private void setCulture()
{
// Extract first element of languages array  
String lang = Request.UserLanguages[0])
// Strip off any weighting appended to the string.
String langOnly = lang.Split(new Char[] {';'})[0];
// Set Culture – sets date-time, currency formats etc
CultureInfo ci = CultureInfo.CreateSpecificCulture(langOnly);
System.Threading.Thread.CurrentThread.CurrentCulture = ci;
// Set the UICulture – defines string resource file
// We support string resources for 'main' language only
// such as en, fr or de
ci = CultureInfo.CreateSpecificCulture(langOnly.Substring(0,2));
System.Threading.Thread.CurrentThread.CurrentUICulture = ci;
}    
}
}

When you build this application and run it with a browser set to each of the supported languages, the output appears as shown in Figure 14-3.

Figure 14-3: Setting the Openwave simulator to different language preferences provides this output for the LocalizingExample application.