Virtual Developer Workshop: Containerized Development with Docker
Do you have an ASP.NET application ready and now you want to translate it into different languages, or are you developing a new application for which you want to support localization? If yes, ASP.NET 2.0 makes it easier to do so than ever before.
In this article, I cover the basics of the globalization and localization support in ASP.NET 2.0. I have included a setup file that creates a Web site with samples for this article.
Globalization and Localization
Globalization is the process of designing your application so that it is possible later to have it translated and support multiple cultures. So, here you might not even actually make any translations but are making the application ready for it. Once you have globalized your application and now want to translate it into a specific culture, the translation process is called localization.
To globalize your application, the most important change to be done is that instead of hard-coding things such as display strings, move them to resource files. You then can set the control properties by reading the resource files. When you want to localize your application, have the resources translated to the languages you want to support. This will be covered in detail in this article.
The Difference Between Culture and Language
Culture consists of language plus the country/region. Culture is usually denoted by a combination of a two-letter lowercase code (called culture code) denoting the language and a two-letter uppercase code (called sub-culture code) denoting the country or region. For example, "de-DE" for German in Germany and "de-AT" for German in Austria (even though the language is the same, they are different cultures!).
Note: A neutral culture is a culture that is associated with a language but not with a country/region, for example, "de" for German.
Culture affects not only things like which language a particular string is shown but also things like the date format used, the decimal separator, currency symbol, and so on.
Culture and UICulture
In ASP.NET, you can set to two culture values: the Culture and UICulture properties. The Culture value determines things such as date, number, currency formatting, and so on. For example, it is the Culture setting that decides whether the date is in the dmy format or mdy format and what names to use for the month and for numeric values what the decimal separator is. The UICulture value determines which resources are loaded for the page. So, it controls things like which translated text to show. In most cases, you will set Culture and UICulture to the same culture.
Culture is set at the thread level by setting the CurrentCulture and CurrentUICulture properties of the thread. You either can set it directly or ASP.NET will set it for you.
In an ASP.NET application, culture can be set in one of these three ways:
- Set it declaratively: In the web.config file or in the @Page directive in the page, you can specify the culture as shown:
- From the client browser's language setting: Here, the user can specify their language of choice through the Languages option in their browser. To see a live example, change your languages option and view the GoogleMail login page. Notice how they change the display language accordingly.
- Set it programmatically: In most cases, you will need to give an explicit way on your Web site for the user to select their language of choice. In such cases, you need to set the culture programmatically. Set these in the InitializeCulture method for the page.
Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(selectedLanguage); Thread.CurrentThread.CurrentUICulture = new CultureInfo(selectedLanguage);
web.config: <globalization uiCulture="es-MX" culture="en-US" /> @Page Directive: <%@ Page UICulture="es-MX" Culture="es-MX" %>
Note: For ASP.NET to use the browser language setting, you need to set the uiCulture and culture settings of web.config and/or the @Page directive to "auto."
Figure 1a: Setting Languages options for Internet Explorer (IE)
Figure 1b: Setting Languages option for Mozilla FireFox
Note: If none of the above are set, ASP.NET will set the Culture and UICulture to that in the Regional Settings of the Web server.
To facilitate localization into different cultures, move strings you want to translate and localizable controls properties to a resource file. For example, if you want to change the string displayed in a Label and its ForeColor depending on the culture, you should move them to a resource file.
The resource file is an XML file and has a resx extension. Each resource in the resx file is in the form of a key-value pair. When you create resource files, start by creating a base .resx file. This is the default, or fallback resource file. For each culture that you want to support, create a copy of the base file and change the name so that it has the same basic file name, but with the culture name as part of it. For example, you might create the following files:
- WebResources.resx: The base resource file. This is the default, or fallback resource file
- WebResources.es.resx: A resource file for Spanish
- WebResources.es-mx.resx: A resource file for Spanish (Mexico)
- WebResources.de.resx: A resource file for German
At run time, ASP.NET uses the resource file that is the best match for the processing thread's CurrentUICulture property (I earlier described the ways in which this property gets set in ASP.NET). For example, if the current UI culture is Spanish (Mexico), resources from WebResources.es-mx.resx will be used. If it's Spanish (Costa Rica), ASP.NET will use WebResources.es.resx as its the best match. If the current UI culture is Swedish (Finland), which has no match in the above case, ASP.NET will use WebResources.resx as its the fallback resource file.
Local and Global Resource Files
Resource files are of two types: local resource files and global resource files.
Local resource files are specific to a single ASP.NET Web page, master page, or user control (.aspx, .master, or .ascx file). The resources in these files can be used only for that ASP.NET Web file. These resource files are put into the special ASP.NET App_LocalResources folder. A local resource file is named after the ASP.NET Web file; for example, the resource file for the Home.aspx Web page could be Home.aspx.resx, Home.aspx.es-mx.resx, and so on.
Note: Each sub-folder of the Web site can have its own App_LocalResources folder.
The resources in a global resource file can be read from any page or code in the Web site. These resource files are put into the special ASP.NET folder App_GlobalResources. This folder exists at the root of the ASP.NET application. Any .resx file that is in the App_GlobalResources folder has global scope.
Figure 2: Resource folders and resource files in a Web site as seen in Solution Explorer
Creating Resource Files
You can create a new resource file in any of the following ways:
- Resource Generator tool (Resgen.exe): You can use this tool to help you generate the XML resouce file. To use this, place the key-value pairs in a text file; for example:
Label1.Text=Hello World! Label1.ForeColor=BlueYou then can use the Resource Generator to generate an XML resource file from this text file. You then can copy this resx file into the global or local resource folder.
- Using the Generate Local Resource option: You can use this option in Visual Studio 2005 to generate local resources for a Web page (.aspx, .master, or .ascx file). Open your page in design view and run this tool. It will generate the base (default) resx file for your page. The tool will move all localizable properties of controls on your page, such as the TextBox's Text property, Label's ForeColor property, and Page's Title property and so on, to the resource file. You then can delete those entries you do not wish to localize.
- Manually: You can add an empty resource file by using the Add New Item option of Visual Studio. You can add resource entries to this file by opening them in Visual Studio's resource editor.