Chapter 15
Localization
What's in this chapter?
Understanding culture types
Getting culture settings from a thread
Declaring culture in ASP.NET
Understanding differences in dates
Understanding differences in currency and numbers
Understanding differences in sorting
Using culture specific resource files
on the Download Code tab. The code is in the chapter 15 download and individually named according to the code filenames noted throughout the chapter.
As the audience for an application expands, businesses often realize they need to globalize the application. Of course, the ideal solution is to build the application to handle an international audience right from the start, but in most cases this may not be feasible because building for localized versions requires extra work and cost.
The core of any localization effort is the translation of resources and user interface changes. Such changes are application specific and, therefore, not really open to generic implementation across the multitude of potential cultures for which you might choose to target an application. However, some common elements of localization, such as date support or numeric and currency formats, can be implemented by .NET Framework classes.
The .NET Framework has made a considerable effort to support the internationalization of .NET applications. API support, server controls, and even Visual Studio itself equip you to do the extra work required to bring your application to an international audience. This chapter looks at some of the important items to consider when building your applications for the world.
), which specifies a language and region using two-letter codes separated by a dash. The following table provides examples of some culture definitions:
| Culture Code | Description |
| en-US | English language; United States |
| en-GB | English language; United Kingdom (Great Britain) |
| en-AU | English language; Australia |
| en-CA | English language; Canada |
| fr-CA | French language; Canada |
The examples in this table define five distinct cultures. These five cultures have some similarities and some differences. Four of the cultures speak the same language (English), so the language code of “en” is used in these culture settings. Following the language setting is the region setting. Even though most of these cultures speak the same language, it is important to distinguish them further by setting their region (such as US for the United States, GB for the United Kingdom, AU for Australia, and CA for Canada). These settings reflect the fact that the English used in the United States is slightly different from the English used in the United Kingdom, and so forth. Beyond language, differences exist in how dates and numerical values are represented. This is why a culture's language and region are presented together.
The differences between the cultures in the table do not break down by region only. Many countries contain more than a single language, and each may have its own preference for notation of dates and other items. For example, en-CA specifies English speakers in Canada. Because Canada is not only an English-speaking country, it also includes the culture setting of fr-CA for French-speaking Canadians.
Understanding Culture Types
The culture definition just given is called a specific culture definition. This definition is as detailed as you can possibly get, defining both the language and the region. The other type of culture definition is a neutral culture definition. Each specific culture has a specified neutral culture with which it is associated. For instance, the English language cultures shown in the previous table are separate, but they also belong to one neutral culture: EN (English). The diagram presented in illustrates how these culture types relate to one another.
Language and culture relationship
From this diagram, you can see that many specific cultures belong to a neutral culture. Higher in the hierarchy than the neutral culture is an invariant culture, which is an agnostic culture setting that should be utilized when passing items (such as dates and numbers) around a network. When performing these kinds of operations, you should make your back-end data flows devoid of user-specific culture settings. Instead, apply these settings in the business and presentation layers of your applications.
In addition, pay attention to neutral culture when working with your applications. In most cases, you are going to build applications with views that are more dependent on a neutral culture than on a specific culture. For instance, if you have a Spanish version of your application, you'll probably make this version available to all Spanish speakers regardless of where they live. In many applications, it won't matter whether the Spanish speaker is from Spain, Mexico, or Argentina. In cases where it does make a difference, use the specific culture settings.
Looking at Your Thread
When the end user requests an ASP.NET page or runs a Windows Forms dialog, the item is executed on a thread from the thread pool. That thread has a culture associated with it. You can get information about the culture of the thread programmatically and then check for particular details about that culture.
To see an example of working with a thread and reading the culture information of that thread, start with the basic WPF application created in Chapter 1. To reproduce this, create a new project called ProVB2012_Localization, and add the appropriate button and text box controls.
Add a new Sub DisplayCultureInfo and have it called by the Click event handler for the test button on the form. When the TestButton_Click event is fired, the user's culture information is retrieved and displayed in the TextBox control. The code for the new Sub is as follows (code file: MainWindow.xaml.vb):
Private Sub DisplayCultureInfo() Dim ci As New System.Globalization.CultureInfo( System.Threading.Thread.CurrentThread.CurrentCulture.ToString()) TextBoxResult.Text = "CURRENT CULTURE'S INFO" & Environment.NewLine TextBoxResult.Text += "Name: " & ci.Name & Environment.NewLine TextBoxResult.Text += "Parent Name: " & ci.Parent.Name & Environment.NewLine TextBoxResult.Text += "Display Name: " & ci.DisplayName & Environment.NewLine TextBoxResult.Text += "English Name: " & ci.EnglishName & Environment.NewLine TextBoxResult.Text += "Native Name: " & ci.NativeName & Environment.NewLine TextBoxResult.Text += "Three Letter ISO Name: " & ci.ThreeLetterISOLanguageName & Environment.NewLine TextBoxResult.Text += "Calendar Type: " & ci.Calendar.ToString() & Environment.NewLineEnd Sub
This simple form creates a CultureInfo object from the System.Globalization namespace and assigns the culture from the current thread that is running using the System.Threading.Thread .CurrentThread.CurrentCulture.ToString call. Once the CultureInfo object is populated with the end user's culture, details about that culture can be retrieved using a number of available properties that the CultureInfo object offers. Example results of running the form are shown in .
US English culture properties
Note that in the code download there is an additional button on the form based on additional changes that are made to this sample project.
The CultureInfo object contains a number of properties that provide you with specific culture information. The items displayed are only a small sampling of what is available from this object. From this figure, you can see that the en-US culture is the default setting in which the thread executes. In addition to this, you can use the CultureInfo object to get at a lot of other descriptive information about the culture. You can always change a thread's culture on the overloads provided via a new instantiation of the CultureInfo object. The following code illustrates commenting out the original default line of code and replacing it with an explicit change of the current culture to Thailand (code file: MainWindow.xaml.vb):
Private Sub DisplayCultureInfo() System.Threading.Thread.CurrentThread.CurrentCulture = New Globalization.CultureInfo("th-TH") Dim ci As Globalization.CultureInfo = System.Threading.Thread.CurrentThread.CurrentCulture ' Dim ci As New System.Globalization.CultureInfo( ' System.Threading.Thread.CurrentThread.CurrentCulture.ToString()) TextBoxResult.Text = "CURRENT CULTURE'S INFO" & Environment.NewLine TextBoxResult.Text += "Name: " & ci.Name & Environment.NewLine TextBoxResult.Text += "Parent Name: " & ci.Parent.Name & Environment.NewLine TextBoxResult.Text += "Display Name: " & ci.DisplayName & Environment.NewLine TextBoxResult.Text += "English Name: " & ci.EnglishName & Environment.NewLine TextBoxResult.Text += "Native Name: " & ci.NativeName & Environment.NewLine TextBoxResult.Text += "Three Letter ISO Name: " & ci.ThreeLetterISOLanguageName & Environment.NewLine TextBoxResult.Text += "Calendar Type: " & ci.Calendar.ToString() & Environment.NewLineEnd Sub In this example, only a couple of lines of code are changed to assign a new instance of the CultureInfo object to the CurrentCulture property of the thread being executed by the application. The culture setting enables the CultureInfo object to define the culture you want to utilize. In this case, the Thai language of Thailand is assigned. The results produced in the TextBox control are illustrated in .
Thailand culture settings
From this figure, you can see that the .NET Framework provides the native name of the language used even if it is not a Latin-based letter style. In this case, the results are presented for the Thai language in Thailand, including some of the properties associated with this culture (such as an entirely different calendar than the one used in Western Europe and the United States).
Declaring Culture Globally in ASP.NET
ASP.NET enables you to easily define the culture that is used either by your entire ASP.NET application or by a specific page within your Web application, using what are termed server-side culture declarations. You can specify the culture for any of your ASP.NET applications by means of the appropriate configuration files. To demonstrate this, close the ProVB2010_Localization application you started with and create a new ASP.NET Empty Web Site called ProVB_Russian. Alternatively, you can open this download folder as a website in Visual Studio 2012. Once the site has been created add a default.aspx page. On this blank page add a new Calendar control from the toolbox, following the text: Welcome to ASP.NET!
To change the default language used by this control, you can specify culture settings in the web.config file of the application itself, as illustrated here (code file: web.config):
<configuration> <system.web> <globalization culture="ru-RU" uiCulture="ru-RU" /> </system.web> </configuration>
Only the <globalization> line will need to be added to your default web.config file; it should also be noted that based on the following page-specific settings, this line has been commented out in the code download.
Note the two attributes represented: culture and uiCulture. The culture attribute enables you to define the culture to use for processing incoming requests, whereas the uiCulture attribute enables you to define the default culture needed to process any resource files in the application (use of these attributes is covered later in the chapter).
Note that one additional option you have when specifying a culture on the server is to define this culture in the root web.config file for the server. Thus, if you are setting up a web server that will be used with only a single culture, you can specify that culture at the server level, instead of needing to specify it as part of the settings for each application running on the server. This can be useful if you are installing Web applications created outside of your native culture, but where you want date, currency, sorting, and similar formats to default appropriately.
In the preceding snippet, the culture established for this ASP.NET application is the Russian language in the country of Russia. In addition to setting the culture at either the server-wide or the application-wide level, another option is to set the culture at the page level, as shown in the following snippet.
<%@ Page Language="VB" AutoEventWireup="false" CodeFile="Default.aspx.vb" Inherits="_Default" UICulture="ru-RU" Culture="ru-RU"%> %>
This example specifies that the Russian language and culture settings are used for everything on the page. You can see this in action by using this @Page directive and a simple Calendar control on the page. shows the output. Notice that marking the page as using Russian settings does not automatically translate text within the page; it only updates the embedded control added to the page.
Using the Russian culture settings on a calendar
Adopting Culture Settings in ASP.NET
In addition to using server-side settings to define the culture for your ASP.NET pages, you also have the option to define the culture according to what the client has set as his or her preference in a browser instance.
When end users install Microsoft's Internet Explorer or some other browser, they have the option to select their preferred cultures in a particular order (if they have selected more than a single culture preference). To see this in action in IE, select Tools ⇒ Internet Options from the IE menu. On the first tab provided (General) is a Languages button at the bottom of the dialog. Select this button and you are provided with the Language Preference dialog shown in .
Changing your language preferences in Internet Explorer
To add any additional cultures to the list, click the Add button and select the appropriate culture from the list. After you have selected any cultures present in the list, you can select the order in which you prefer to use them. Thus, a user with multiple settings in this list will have a version of the application with their first language choice before anything else; if a version that supports that language is not available, their second and then consecutive versions are checked. The first available language matching one of their preferences will be presented.
Making language selections, the end user can leverage the automatic culture recognition feature provided in ASP.NET. Instead of specifying a distinct culture in any of the configuration files or from the @Page directive, you can also state that ASP.NET should automatically select the culture provided by the end user requesting the page. This is done using the auto keyword, as illustrated here:
<%@ Page UICulture="auto" Culture="auto" %>
With this construction in your page, the dates, calendars, and numbers appear in the preferred culture of the requester. What happens if you have translated resources in resource files (shown later in the chapter) that depend on a culture specification? Or what if you have only specific translations and therefore can't handle every possible culture that might be returned to your ASP.NET page? In this case, you can specify the auto option with an additional fallback option if ASP.NET cannot find any of the culture settings of the user (such as culture-specific resource files). This usage is illustrated in the following code:
<%@ Page UICulture="auto:en-US" Culture="auto:en-US" %>
In this case, the automatic detection is utilized; but if the culture preferred by the end user is not present, then en-US is used.
. Different Date/Time formats by culture
Different Date/Time formats by culture
Clearly, the formats used to represent a date/time value can be dramatically different between cultures—some, such as Saudi Arabia (ar-SA) and Thailand, (th-TH) use entirely different calendar baselines.
Differences in Numbers and Currencies
In addition to date/time values, numbers are displayed quite differently from one culture to the next. How can a number be represented differently in different cultures? Well, it has less to do with the actual number (although certain cultures use different number symbols) and more to do with how the number separators are used for decimals or for showing amounts such as thousands, millions, and more. For instance, in the English culture of the United States (en-US), numbers are represented in the following fashion:
5,123,456.00
From this example, you can see that the en-US culture uses a comma as a separator for thousands and a period for signifying the start of any decimals that might appear after the number is presented. It is quite different when working with other cultures. The following snippet shows an example of representing numbers in other cultures (code file: MainWindow.xaml.vb):
Private Sub Numbers() Dim myNumber As Double = 5123456.0 Thread.CurrentThread.CurrentCulture = New CultureInfo("en-US") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("n") & Environment.NewLine Thread.CurrentThread.CurrentCulture = New CultureInfo("vi-VN") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("n") & Environment.NewLine Thread.CurrentThread.CurrentCulture = New CultureInfo("fi-FI") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("n") & Environment.NewLine Thread.CurrentThread.CurrentCulture = New CultureInfo("fr-CH") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("n") & Environment.NewLine End Sub Adding this code to your project and running it from the click event produces the results shown in .
Different numeric formats across cultures
As you can see, cultures show numbers in numerous different formats. The second culture listed in the figure, vi-VN (Vietnamese in Vietnam), constructs a number exactly the opposite from the way it is constructed in en-US. The Vietnamese culture uses periods for the thousand separators and a comma for signifying decimals, a somewhat common format around the world. Finnish uses spaces for the thousand separators and a comma for the decimal separator, whereas the French-speaking Swiss use an apostrophe for separating thousands, and a period for the decimal separator. This demonstrates that not only do you need to consider dates and language constructs, but that it is also important to “translate” numbers to the proper format so that users of your application can properly understand the numbers represented.
Another scenario in which you represent numbers is when working with currencies. It is one thing to convert currencies so that end users understand the proper value of an item; it is another to translate the construction of the currency just as you would a basic number.
Each culture has a distinct currency symbol used to signify that a number represented is an actual currency value. For instance, the en-US culture represents currency in the following format:
$5,123,456.00
The en-US culture uses a U.S. dollar symbol ($), and the location of this symbol is just as important as the symbol itself. For en-US, the $ symbol directly precedes the currency value (with no space in between the symbol and the first character of the number). Other cultures use different symbols to represent currency and often place those currency symbols in different locations.
Create another Sub that can be called from the button's click event handler, and this time format the same numbers using the built-in .NET currency formatting shown here (code file: MainWindow.xaml.vb):
Private Sub Currency() Dim myNumber As Double = 5123456.0 Thread.CurrentThread.CurrentCulture = New CultureInfo("en-US") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("c") & Environment.NewLine Thread.CurrentThread.CurrentCulture = New CultureInfo("vi-VN") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("c") & Environment.NewLine Thread.CurrentThread.CurrentCulture = New CultureInfo("fi-FI") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("c") & Environment.NewLine Thread.CurrentThread.CurrentCulture = New CultureInfo("fr-CH") TextBoxResult.Text += Thread.CurrentThread.CurrentCulture.EnglishName & " : " & myNumber.ToString("c") & Environment.NewLine End Sub Executing this code displays the output shown in .
Formatting currency across cultures
Not only are the numbers constructed quite differently from one another, but the currency symbol and the location of the symbol in regard to the number are quite different as well.
Note that when you are using currencies on an ASP.NET page and you have provided an automatic culture setting for the page as a whole (such as setting the culture in the @Page directive), you need to specify a specific culture for the currency that is the same in all cases. Unlike dates, for which the differences are primarily display oriented, with a currency there is an expectation of value conversion. Thus, reformatting a currency can cause expensive errors unless you are actually doing a currency conversion.
For instance, if you are specifying a U.S. dollar currency value in your data, you do not want your ASP.NET page to display that value as something else (for example, the euro) based on translating the remainder of the page information to another language. Of course, if you actually performed a currency conversion and showed the appropriate euro value along with the culture specification of the currency, that makes sense and is the best solution.
Therefore, if you are using an automatic culture setting on your ASP.NET page and you are not converting the currency, you should perform something similar to the following code for currency values:
Dim myNumber As Double = 5123456.00 Dim usCurr As CultureInfo = New CultureInfo("en-US") Response.Write(myNumber.ToString("c", usCurr)) Understanding Differences in Sorting
You have learned to translate textual values and alter the construction of the numbers, date/time values, currencies, and more when you are globalizing an application. You should also take care when applying culture settings to some of the programmatic behaviors that you establish for values in your applications. One operation that can change based upon the culture setting applied is how .NET sorts strings. You might think that all cultures sort strings in the same way (and generally they do), but sometimes differences exist. For example, the following snippet shows a sorting operation occurring in the en-US culture (code file: MainWindow.xaml.vb):
Private Sub Sorting() Thread.CurrentThread.CurrentCulture = New CultureInfo("en-US") 'Thread.CurrentThread.CurrentCulture = New CultureInfo("fi-FI") Dim myList As List(Of String) = New List(Of String) myList.Add("Washington D.C.") myList.Add("Helsinki") myList.Add("Moscow") myList.Add("Warsaw") myList.Add("Vienna") myList.Add("Tokyo") myList.Sort() For Each item As String In myList TextBoxResult.Text += item.ToString() & Environment.NewLine Next End Sub For this example to work, you have to reference the System.Collections and the System.Collections.Generic namespaces, because this example makes use of the List(Of String) object.
In this example, a generic list of capitals from various countries of the world is created in random order. Then the Sort method of the generic List(Of String) object is invoked. This sorting operation sorts the strings according to how sorting is done for the defined culture in which the application thread is running. The preceding code shows the sorting as it is done for the en-US culture. The result of this operation when used within the ProVB2012_Localization form is shown in .
Typical sorting in English
This is pretty much what you would expect. Now, however, change the previous example so that the culture is set to the Finnish culture. Do this by uncommenting the second line of the Sub Sorting and commenting out the first line of the Sub Sorting which sets the “en-US” culture settings, in the preceding snippet.
If you run the same bit of code under the Finnish culture setting, you get the results presented in .
Finnish cultural setting impact on sorting
Comparing the Finnish culture sorting shown in and the U.S. English culture sorting done in , you can see that the city of Vienna is in a different place in the Finnish version. This is because in the Finnish language, there is no difference between the letter V and the letter W. Therefore, if you are sorting using the Finnish culture setting, Vi comes after Wa, and thus Vienna appears last in the list of strings in the sorting operation.
