Localization in ASP.NET 2.0 and Visual Studio .NET 2005
This topic is pre-release documentation and is subject to change in future releases.
Tested against Visual Studio .NET 2005, v8.0.40301.9 and the .NET Framework v2.0.40301
Part 1 : Code free Localization
Visual Studio .NET 2005 and ASP.NET 2.0 offer some great features for beginners in the Localization arena. With the new designer support in Visual Studio it's possible to Localize your whole website without writing a single line of code. That includes full support for other Cultures and Languages.
In this part of the Localization in ASP.NET 2.0 and Visual Studio .NET 2005 series, I hope to explore the Codeless Localization provided.
Adding a Localized Label to your Web Form
Create a new Web Site in Visual Studio .NET 2005, then on the Default.aspx page, add a Label. The HTML for the page will look like this: -
<%@ page language="C#" %>
<script runat="server">
</script>
<html>
<head runat="server">
<title>My Localized Page</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Label ID="Heading" Runat="server">
</asp:Label>
</div>
<div>
</div>
</form>
</body>
</html>
You can see a Label on the page above. Now making sure you're in Design View, go to the Tools Menu and Click on the "Generate Page Resource" (GPR) entry.
A Folder will have been created in the same place as your Default.aspx page called "LocalResources". Within that folder there will be a file called Default.aspx.resx.
If you switch to Source View on your Default.aspx page you'll notice some changes to your HTML Code: -
<%@ page language="C#" meta:resourceKey="PageTitleResource1" %>
<script runat="server"> </script>
<html>
<head runat="server">
<title>My Localized Page</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Label ID="Heading" Runat="server" meta:resourcekey="LabelResource1">
</asp:Label>
</div>
<div>
</div>
</form>
</body>
</html>
What Visual Studio has done is parse all the Controls on your Web Form (Default.aspx) searching for any marked with the [Localizable(true)] attribute set (to true). This tells Visual Studio .NET and the .NET Framework that the control contains Properties that are Localizable (i.e. contain Textual Content such as the Text and ToolTip properties on a System.Web.UI.WebControl.Label control).
When Visual Studio finds a Localizable control whilst running the GPR command, any Localizable properties on a control are added to the .resx file for the associated .aspx in the LocalResources folder. Visual Studio also marks each Localizable control with a specific MetaData property with a ResourceKey category such as meta:resourcekey="LabelResource1" on the Label control.
Opening the .resx file shows the following Resource Keys have been added: -
- LabelResource1.Text
- LabelResource1.ToolTip
- PageTitleResource1
The PageTitleResource1 key has a value of "My Localized Page" pulled directly from the <title /> portion of the .aspx.
If the page is executed as is, the page will display with no content, as expected. Adding a value to the LabelResource1.Text entry in the .resx file "Walk" for example, and then reloading the page will cause that value ("Walk") to be displayed as the Text of the Label control.
Localizing the web page from this point is very simple, firstly a copy of the .resx file needs to be made and placed in the LocalResources folder associated with the .aspx file. Rename the file for the appropriate culture, such as French-French (fr-FR), to be called Default.aspx.fr-fr.resx.
Within the Default.aspx.fr-fr.resx file are the Resources that were in the Default.aspx.resx file, editing the value "Walk" for LabelResource1.Text to "Paid" will complete the French version of the Web Page. Loading the page at this point will still load the default non-culture specific .resx file.
One way to show the French Resources is to change the UICulture property of the page to the appropriate culture (fr-FR). If the Property UICulture="fr-fr" is added to the Page directive and the page is reloaded you will see "Paid" load on the page.
Whilst this is handy, ASP.NET 2.0 has some even cooler features baked right in to the Framework, one of which is automatically sensing a clients culture and loading the appropriate resources based on this. Modern browsers send a value with each HTTP Request indicating the preferred culture. The Browser I am currently using (IE 6.0) sends a value of en-GB (British English) to the web server with each request.
It is quite simple to turn on the automatic Resource loading based on the browser client's preffered culture. Change the UICulture property's value to "auto" so it reads UICulture="auto" then save and reload the page. You will see that (unless you're using a French browser!) that the value displayed on the page has returned to "Walk". This is because the Web Server has decided to revert to the default .resx file as it cannot find a .resx file for your culture.
Change the default culture on your browser, on IE 6 this can be done by going to: -
- Tools
- Internet Options
- Languages
- Adding French
- Clicking "Move Up" to make French the Top entry on the list.
Reload the Page, you will see that the Web Server has picked up your client settings and automatically served you the French Resources.
Don't forget to set your Browser back to the correct Language before continuing (or things might get a little confusing).
So there's how you can get simple Localization in ASP.NET 2.0, in the next article I'll talk about the other ways you can access Resources using code, some of that is even cooler than the above.