Walkthrough: Using Resources for Localization with ASP.NET
An effective way to create localized Web pages is to use resource objects for your page's text and controls. By using properties placed in resource objects, ASP.NET can select the correct property at run time according to the user's language and culture. The process is straightforward:
A set of resource files (.resx), one file for each language, stores localized text.
In your page, you indicate that controls should use resources for their property values.
At run time, the browser indicates the user's preferred language, ASP.NET selects the appropriate .resx file, and the controls' property values are derived from the resource file.
Visual Web Developer allows you to generate and use resources without writing any code. (You can also use custom resource objects, such as a database. However, in this walkthrough you will use a .resx file to store values.)
Tasks illustrated in this walkthrough include:
Enabling localization of ASP.NET pages.
Generating a resource file and implicitly associating its values with the controls in your application.
Creating localization resource files and explicitly referencing them in your pages by using declarative expressions.
Prerequisites
In order to complete this walkthrough, you will need:
Visual Studio (not Microsoft Visual Web Developer Express).
Note
This walkthrough assumes that you selected the Web Development collection of settings the first time that you started Visual Studio. For more information, see How to: Select Web Development Environment Settings.
The .NET Framework.
Creating a Web Site
If you have already created a Web site in Visual Web Developer (see Walkthrough: Creating a Basic Web Forms Page in Visual Studio), you can use that Web site and go to the next section, "Implicit Localization with ASP.NET." Otherwise, create a new Web site and page.
This walkthrough uses a Web site project. You could use a Web application project instead. For information about the difference between these Web project types, see Web Application Projects versus Web Site Projects in Visual Studio.
To create a file system Web site
Open Visual Studio.
In the File menu, click New Web Site.
The New Web Site dialog box is displayed.
Under Installed Templates, click Visual Basic or Visual C# and then select ASP.NET Web Site.
In the Web location box, select File System, and then enter the name of the folder where you want to keep the pages for your Web site.
For example, type the folder name C:\WebSites.
Click OK.
Visual Studio creates a Web site project that includes prebuilt functionality for layout (a master page, the Default.aspx and About.aspx content pages, and a cascading style sheet), for Ajax (client script files), and for authentication (ASP.NET membership).
Implicit Localization with ASP.NET
In this section, you will work with implicit localization. In implicit localization, you specify that control properties should automatically be read from a resource file, but you do not need to explicitly specify which properties are localized. Then, you create a resource file with localized values for specific properties. At run time, ASP.NET examines the controls on the page. If the control is marked to use implicit localization, ASP.NET looks through the resource file for the page. If it finds property settings for the marked control, ASP.NET substitutes the values in the resource file for those in the control.
In this example of implicit localization, you use a combination of the designer and the Resource Editor to generate a default resource file that you will use as a starting point for localization in two languages. Visual Web Developer will generate a resource file based only on the controls on your page. For this reason, it is a good idea to generate the resource file after you have completed your page's control layout, including simple controls such as buttons, labels, and text boxes.
To place controls on a page
In Solution Explorer, right-click the project and select Add New Item.
The Add New Item dialog box is displayed.
Under Installed Templates select Visual Basic or Visual C#, and then select Web Form.
Enter Sample.aspx as the name for the new Web page and then click Add.
Switch to Design view.
In the Toolbox, from the Standard section, drag a Button, a Label, and a TextBox control onto the page.
For each control, set Text to English Button, English Label, and English TextBox, respectively.
After creating the page and adding the controls, you can use a Visual Web Developer command to generate a local resource file for this page. The local resource file will contain the resource strings for the controls on the page. Visual Web Developer generates a resource string for each property that is designated internally in the control as localizable. Each control can have different properties designated as localizable, although most text-based properties are marked that way.
To automatically generate a resource file
Click the designer surface or a control.
On the Tools menu, click Generate Local Resource.
Visual Web Developer creates a new folder named App_LocalResources, and within the App_LocalResources folder, a new file named Sample.aspx.resx. If you named your page something other than Sample.aspx, the .resx file will reflect whatever name you chose. When using implicit localization, resource file names are based on individual page names.
Switch to Source view to see the changes to your control declarations.
Visual Web Developer has added an attribute to your controls to retrieve their values from your newly created resource file. For example, the Button control's markup has a new meta:resourcekey attribute.
<asp:Button ID="Button1" Runat="server" meta:resourcekey="ButtonResource1" Text="English Button" />
When a browser sends a request to Web server, the request can include information about the current language and culture. For example, a browser might send the string "en-us" to indicate it has been set to use United States English; another browser might send the string "en-gb" to indicate it has been set to use British English.
Note
The language and culture settings in a browser request are not a completely reliable way to detect the user's preferred language. The settings indicate only what the browser has been set to send or has inherited from the underlying operating system. For this walkthrough, you will rely on the language and culture settings, but in a production application you should also include a way for users to select a language and culture manually.
The resource file is used as the default resource file for all requests. (It is the resource file for the fallback culture.) If no culture is specified by the browser, or if the browser request includes a language or culture that you do not support, resource values are pulled from this default file.
Now that the resource file is created, you can place localized text within it by using the Resource Editor.
To edit the resource file by using the Resource Editor
In Solution Explorer, open Sample.aspx.resx.
In the Resource Editor, under Value, are the Text properties for each of the controls that you placed onto your page. Changing the value here will change the value for the default culture.
Set ButtonResource1.Text to Edited English Text.
Save the file.
Now you can test the page.
To test the page
Switch to the Sample.aspx page.
Press CTRL+F5 to run the page.
The text you provided in the Resource Editor is shown as the label for Button1. When using implicit localization, syntax properties in resource files will override properties specified in the page itself.
Adding Other Cultures
Each language and culture combination requires a unique resource file. To add other cultures, you can use your default file as a starting point. You can create resource files for different cultures and locales by creating new resource files in which the ISO language codes are part of the file name (for example, en-us, fr-ca, and en-gb). These ISO codes are placed between the page name and the .resx file name extension, as in Sample.aspx.en-us.resx. To specify a culturally neutral language, you would eliminate the country code, such as Sample.aspx.fr.resx for the French language.
Note
When using implicit localization syntax, you must create a separate series of resource files for each page.
To create a culturally neutral French language file
In Solution Explorer, right-click the Sample.aspx.resx file, and then click Copy.
Right-click the App_LocalResourcesfolder, and then click Paste.
Visual Web Developer creates a file named Copy of Sample.aspx.resx.
Right-click the Copy of Sample.aspx.resx file, click Rename, and then type Sample.aspx.fr.resx.
Sample.aspx.fr.resx indicates a file for culturally neutral French language text.
Open Sample.aspx.fr.resx.
For the Button, Label, and TextBox controls, set Text to French Button, French Label, and French TextBox, respectively.
Save the file.
Testing with an Alternate Language Setting
Before you can see if this new resource file is used by ASP.NET, you must alter your browser settings to request the desired culture.
To change your browser's language settings
In Microsoft Internet Explorer, on the Tools menu, click Internet Options.
Click Languages.
In the Language Preference dialog box, click Add.
In the Add Language dialog box, under Languages, click French (France) [fr-fr], and then click OK.
Click Add and add Spanish (Mexico) [es-mx] to the list of languages.
Click Add and add Arabic (Egypt) [ar-eg] to the list of languages.
You will use Spanish and Arabic for testing later in this walkthrough.
In the Language Preference dialog box, under Language, click French (France) [fr-fr], click Move Up, and then click OK.
Internet Explorer is now set to pass fr-fr as the language setting for any request. With the culture set to auto in the Sample.aspx page, ASP.NET will attempt to locate a resource file and its corresponding values to assemble the page according to your language and culture preferences.
To test the page
In Visual Web Developer, press CTRL+F5 to run the page.
The page is refreshed with values from the localized French language file instead of the English version.
Note
You can reset your language settings in Internet Explorer by returning to the Language Preference dialog box and moving your chosen language back up in the list.
Explicit Localization with ASP.NET
In the first part of this walkthrough, you used ASP.NET implicit localization to have controls display localized text. You generated a resource file with property values in it, and in the process, you added an attribute to each control that instructed it to fill its property values, if any, from the resource file. Implicit localization works automatically, in that you do not need to specify property by property how to read information from a resource file.
However, at times you want to have more direct control over how properties are set. For this, instead of using implicit localization, you can use explicit localization. With explicit localization, you set the value of a property by using an expression pointing to a resource file. When the page runs, the expression is evaluated, the value is read from the specified resource file, and then the value is used to set the property.
Explicit localization is useful when you have large bodies of text or custom messages you want to localize, in addition to controls and labels. For example, you could develop a series of localized welcome and thank you messages for an e-commerce site, and use explicit declarative expressions to place this text on your pages. Additionally, explicit localization allows you to maintain a single set of localized resource files rather than maintaining a separate set of files for each page.
In this section, you will create resource files manually and reference them by using ASP.NET declarative expression syntax. You will create a resource file for a simple thank you message. Unlike using the designer, a separate resource file is not required for each ASP.NET page.
The base name of your resource file will be LocalizedText. For each language you want to localize, you will create another file with the appropriate language code (and optionally the culture code) as part of the file name. For example, for U.S. English you would create a file named LocalizedText.resx. For the French language in Canada, you would create a file named LocalizedText.fr-ca.resx. Both files would be placed under the Resources directory of your Web application. Unlike the implicit example previously, you do not need to maintain a resource file for each .aspx page; instead, you can maintain a single series of files for each language or culture you support.
To create a resource file
In Solution Explorer, right-click the root of your Web site, click Add ASP.NET Folder, and then click App_GlobalResources.
Right-click the App_GlobalResources folder, and then click Add New Item.
In the list, click Resource File.
In the Name box, type LocalizedText.resx, and then click Add.
The LocalizedText.resx file will act as the resource for the fallback culture.
Create a second .resx file and name it LocalizedText.fr.resx.
The string "fr" identifies the file as the resource to use if the browser's language is set to French (regardless of culture).
Create a third .resx file and name it LocalizedText.es-mx.resx.
The string "es-mx" identifies the file as file as the resource to use if the browser's language is set to Spanish (Mexico).
Open the LocalizedText.resx file.
In the first row under the Name column type Msg1.
In the first row under the Value column, type Hello.
Save the file and close it.
Open the LocalizedText.fr.resx, create a resource string named Msg1, assign it the value Bon jour. When you are finished, save and close the file.
Open the LocalizedText.es-mx.resx, create a resource string named Msg1, assign it the value Buenos días. When you are finished, save and close the file.
Note
To insert the letter with acute (í), type ALT+0237 on the numeric keypad with Number Lock on.
You have created three values for the resource named Msg1. ASP.NET will read the value out of the appropriate resource file based on what language the browser is set to.
Now that your resource file is created, you can return to the page and add controls that will reference the resource.
To add a Label control to the page
Switch to Sample.aspx, and then switch to Design view.
Drag another Label control onto the page.
Right-click the Label control, click Properties, and then click the ellipsis (…) button in the Expressions box.
The Expressions dialog box appears.
In the Bindable Properties list, click Text.
In the Expression Type list, select Resources.
Under Expression Properties, set ClassKey to LocalizedText and ResourceKey to Msg1.
Click OK.
Switch to Source view.
Your label's text attribute now has an explicit expression stating the base file from which to retrieve the resource and the key to select.
<asp:Label ID="Label2" Runat="server" Text="<%$ Resources:LocalizedText, Msg1 %>"></asp:Label>Note
The LocalizedText attribute has no language indicator, culture indicator, or .resx extension, because it is not the actual file name. Instead, LocalizedText represents the base resource class. Depending on the culture sent by the browser, ASP.NET will select the resource out of the file with the appropriate language or culture code within its file name, such as LocalizedText.fr.resx, LocalizedText.es-mx.resx, or if no matching language is found, LocalizedText.resx.
With the resource file completed, and the declarative expression added, you can test the page. After the last test, your browser was set to report French as its language preference. During the testing, you will change the browser's language several times.
To test the page
Press CTRL+F5 to run the page.
The French-language version of the text you provided in the Resource Editor is shown as the text for the Label control.
In Microsoft Internet Explorer, on the Tools menu, click Internet Options.
Click Languages.
In the Language Preference dialog box, move Spanish (Mexico) [es-mx] to the top of the list of languages. When you are finished, click OK and close the Internet Options dialog box.
Press F5 to refresh the browser.
The Spanish version of the text is displayed.
Change the language to Arabic and then press F5 to refresh the page again.
This time, the text is displayed in the language you used in the fallback resource file. Because you did not create a file LocalizedText.ar-eg.resx, ASP.NET was not able to locate text that matched the language and culture reported by the browser, so it used the fallback resource file.
When you are finished testing the page, set the language back to the language your preferred language.
Next Steps
Localization can be a complex undertaking. This walkthrough has illustrated some of the features in Visual Web Developer that can eliminate some of the work. You might want to learn more about localization and ASP.NET. For example, you might want to:
Learn more about using resources in your applications. For details, see Resources in Desktop Apps.
Use classes that define culture-related information, including the language, country or region, calendars in use, format patterns for dates, currency, numbers, and sort order for strings. For details, see System.Globalization.
Learn more about best practices to use when coding for a global audience. For details, see Best Practices for Developing World-Ready Applications.
See Also
Other Resources
Globalizing and Localizing .NET Framework Applications