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.
Under Visual Studio installed templates, 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.
.gif) 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 %>">
| 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.