TOC

The community is working on translating this tutorial into Italian, but it seems that no one has started the translation process for this article yet. If you can help us, then please click "More info".

Localization:

Hello, localized world!

With the knowledge acquired from the previous chapters, let's try actually localizing some text, to see that it works. You should create a new project in Visual Studio. You can use the default page added, or create a new one for the purpose. The content should look something like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="Test.aspx.cs" Inherits="Test" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Demo</title>
</head>
<body>
    <form id="form1" runat="server">
        <asp:Label runat="server" ID="lblHelloWorld" Text="Hello, world!" />
    </form>
</body>
</html>

If you run it, you will get the good old "Hello, world!" message, in plain English as expected. Now let's add some localization magic to it. We will use local, implicit localization for this - both are new terms, which will be explained later on. For now, just right click on your project and from the Add ASP.NET folder sub menu, select App_LocalResources. This is the folder where we place local resources, each of them specific to a file in your project.

Now, right click this new folder, and add a new item. This should be a Resource file, and the name should be the same as your page, but with a .resx extension. For instance, I called my page Test.aspx, so my Resource file should be named Test.aspx.resx. This part is important - if we want ASP.NET to automatically map a resource file to a specific ASP.NET page, the names should be like this. This is our default resource file, used to keep the default version of our strings. Let's add a couple of other languages. Once again, the filename is used to map the resource file, so for instance, to add a German language file, the name should be <filename>.aspx.de.resx, or in the culture specific version: <filename>.aspx.de-DE.resx

I have added Test.aspx.de-DE.resx and Test.aspx.es-ES.resx, to translate the page into German and Spanish. Then I add a new row to Test.aspx.resx, with the name lblHelloWorld.Text. In my project, English is the default language, so I give this row a value of "Hello, world!". I then open Test.aspx.de-DE.resx, add a row with the same name as before, and set the value to "Hallo, Welt!". I do the same for Test.aspx.es-ES.resx, where I set the value to "Hola, mundo!". Your three resource files should now all have a row with the name of "lblHelloWorld.Text", and a localized version of the Hello world string.

Now, go back to our ASP.NET page and use the meta:resourcekey property on our Label control, to make it use our resource string. It should look like this:

<asp:Label runat="server" ID="lblHelloWorld" Text="Hello, world!" meta:resourcekey="lblHelloWorld" />

As you can see, I've used the same string as for the ID of the control. You probably remeber that we added a resource row with the name of "lblHelloWorld.Text". This corresponds to a control with the resource key of "lblHelloWorld", mapped to the Text property of this control. Now, try setting the UICulture property on your page and run the example:

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="Test.aspx.cs" Inherits="Test" UICulture="de-DE" %>

The label is now in German. Change UICulture to "es-ES" and reload the page. It's now in Spanish. Then try changing it to something completely different, like fr-FR, and you will see our default language used instead, simply because we don't have a localized version of the string in French.

This was a simple example, to show you how it can work, but you need a bit more information about HOW it works. In the next couple of chapters we will look into local and global localization, as well as implicit and explicit localization. First up is the CultureInfo class though, since it's used heavily when doing localization.


This article has been fully translated into the following languages: Is your preferred language not on the list? Click here to help us translate this article into your language!