3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

Walkthrough: Using
Resources for
Localization with
ASP.NET
Visual Studio 2005

39 out of 71 rated this helpful

An effective way to create localized Web pages is to use resources

for your page's text and controls based on the user's language and
culture. 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 resource file (.resx) stores values.
In your page, you indicate that controls should use
resources for their property values.
At run time, the controls' property values are derived from
the resource file.
Note
In practice, you can store values in custom resources
objects, such as a database. However, in this
walkthrough you will use a .resx file to store values.
Visual Web Developer allows you to generate resources for
controls, control properties, and HTML for your controls without
writing any code.
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:
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

1/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

In order to complete this walkthrough, you will need:

Visual Web Developer (Visual Studio).
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 Page in Visual Web
Developer), 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 by using the steps in the following
procedure.

To create a file system Web site

1. Open Visual Web Developer.
2. On the File menu, click NewWeb Site.
The New Web Site dialog box appears.
3. Under Visual Studio installed templates, click ASP.NET
Web Site.
4. In the Location box, enter the name of the folder where
you want to keep the pages of your Web site.
For example, type the folder name C:\WebSites.
5. In the Language list, click the programming language
you prefer to work in.
6. Click OK.
Visual Web Developer creates the folder and a new page
named Default.aspx.

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.
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

2/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

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

1. In Solution Explorer, right-click Default.aspx, click
Rename, and then type Sample.aspx.
Doing this will help avoid confusion in the rest of the
walkthrough with regard to default resource files
because implicit resource file names use page names.
2. Open Sample.aspx, and then switch to Design view.
3. In the Toolbox, from the Standard section, drag a
Button, a Label, and a TextBox control onto the page.
4. 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

1. Click the designer surface or a control.
2. 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.
3. Switch to Source view to see the changes to your
control declarations.
Visual Web Developer has added an attribute to your
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

3/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

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="se

rver" meta:resourcekey="ButtonReso
urce1" 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
1. 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.
2. Set ButtonResource1.Text to Edited English Text.
3. Save the file.
Now you can test the page.

msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

To test the page

4/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

To test the 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
1. In Solution Explorer, right-click the Sample.aspx.resx
file, and then click Copy.
2. Right-click the App_LocalResourcesfolder, and then
click Paste.
Visual Web Developer creates a file named Copy of
Sample.aspx.resx.
3. 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.
4. Open Sample.aspx.fr.resx.
5. For the Button, Label, and TextBox controls, set Text
to French Button, French Label, and French TextBox,
respectively.
6. Save the file.
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

5/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

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

1. In Microsoft Internet Explorer, on the Tools menu, click
Internet Options.
2. Click Languages.
3. In the Language Preference dialog box, click Add.
4. In the Add Language dialog box, under Languages,
click French (France) [fr], and then click OK.
5. Click Add and add Spanish (Mexico) [es-mx] to the list
of languages.
6. 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.
7. In the Language Preference dialog box, under
Language, click French (France) [fr], click Move Up,
and then click OK.
Internet Explorer is now set to pass 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.

msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

6/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

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 ecommerce 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

1. In Solution Explorer, right-click the root of your Web
site, click Add ASP.NET Folder, and then click
App_GlobalResources.
2. Right-click the App_GlobalResources folder, and then
click Add New Item.
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

7/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

3. Under Visual Studio installed templates, click

Resource File.
4. In the Name box, type LocalizedText.resx, and then
click Add.
The LocalizedText.resx file will act as the resource for
the fallback culture.
5. 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).
6. Create a third .resx file and name it LocalizedText.esmx.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).
7. Open the LocalizedText.resx file.
8. In the first row under the Name column type Msg1.
9. In the first row under the Value column, type Hello.
10. Save the file and close it.
11. 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.
12. Open the LocalizedText.es-mx.resx, create a resource
string named Msg1, assign it the value Buenos das.
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

1. Switch to Sample.aspx, and then switch to Design view.
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

8/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

2. Drag another Label control onto the page.

3. Right-click the Label control, click Properties, and then
click the ellipsis () button in the Expressions box.
The Expressions dialog box appears.
4. In the Bindable Properties list, click Text.
5. In the Expression Type list, select Resources.
6. Under Expression Properties, set ClassKey to
LocalizedText and ResourceKey to Msg1.
7. Click OK.
8. 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="serv

er" Text="<%$ Resources:LocalizedT
ext, Msg1 %>">

Note
The LocalizedTextattribute has no language
indicator, culture indicator, or .resx extension
because it is not the actual file name. Instead,
LocalizedTextrepresents 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

1. 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.
msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

9/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

control.

2. In Microsoft Internet Explorer, on the Tools menu, click

Internet Options.
3. Click Languages.
4. 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.
5. Press F5 to refresh the browser.
The Spanish version of the text is displayed.
6. 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.
7. 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 Applications.
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.

msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

See Also

10/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

See Also

Concepts

Using the CultureInfo Class

Other Resources

Encoding and Localization

Globalization and Localization Namespaces in Visual Studio

Community Additions

japanese
because for japanese you have to use .ja

interestingly though i've just created a transalation for a japanese

resource file and i find the resourcemanager is not able to
correctly select the text for username or password in my files. not
sure why.
373K
9/16/2011

Japanese Locale: The namespace 'Resources'

already contains a definition for
'LocalizedText'
I followed the Walkthrough for the "Explicit Localization with
ASP.NET" section step by step and had no issue. French and
Spanish worked fine.

However, when I try creating the resource file "LocalizedText.jp", I

get the error "The namespace 'Resources' already contains a
definition for 'LocalizedText'". I"m using VS2010 & .NET 4.0. I've
tried it again using a new, blank asp.net project, and get the exact
same issue. Why is this not working for Japanese?
jaguth2
9/7/2011

ditto to "Make sure to enable Globalization in

web.config "
Adding this entry to the web.config also made it work for me. I
am using Visual Studio 2010 and .NET 3.5.

msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

11/12

3/27/13

Walkthrough: Using Resources for Localization with ASP.NET

<configuration>
<system.web>
<globalization culture="auto" uiCulture="auto"
enableClientBasedCulture="true"/>

Joseph Fluckiger2
8/18/2010

Make sure to enable Globalization in

web.config
When I walked through this I found that I had to add the following
to the web.config in order to ASP.NET to automatically pick up on
the culture being supplied by the browser:

<globalization culture="auto" uiCulture="auto"

enableClientBasedCulture="true"/>

This sets the culture and uiCulture properties on the current

Thread to be set to what the browser is supplying. This article
doesn't mention this so I wonder if it is an oversight or if
templates for new projects have this in the web.config already.

MikeVWood
11/11/2009

2013 Microsoft. All rights reserved.

msdn.microsoft.com/en-us/library/fw69ke6f(v=vs.80).aspx

12/12