Localization #1: The basics

As you can already guess from the word “basics” in the title: This is an easy one – but nevertheless quite useful if you want to increase your app’s audience by adding multi-language support. (And to those readers who know already everything about app localization: Don’t be discouraged by the term “basics” and look at another part of the title where it states “#1” – yes, this is only the first of probably four blog posts covering localization. You might skip this one, but be sure to return to #2 to #4 as I’ll dive deeper into the topic and its connection to MVVM, data binding and portable class libraries!)

Defining resources:

To enable automatic language switching, you must ensure that string values (captions of user controls, explanations, etc.) are not defined directly in C#/VB or XAML code, instead you should insert all those values into a resource file and accompany them with descriptive keys. For each language to be supported by your App, a separate resource file is needed. All those different language resource files should, of course, contain the same keys, accompanied by translated string values.

English and German resource files

In a Windows Phone 8 App, resource files are created automatically. The Resources folder contains already a file called AppResources.resx, which contains the string value in your App’s default language. As soon as you add supported cultures to the App’s properties (right-click the project name in Solution Explorer and choose “Properties”), they are automatically added to the WMAppManifest’s Packaging page, and an additional resource file is created that has the same name as the first one, but with the desired culture code as suffix (e.g., “AppResources.de.resx” for German language).

(Note: Instead of just choosing “German”, you could also create separate resource files for German-speaking regions. In this case, choose all the appropriate “German (…)” options (“German (Germany)”, “German (Austria)”, etc.) from the supported cultures. The associated resource files will be named “AppResources.de-DE.resx”, “AppResources.de-AT.resx”, an so on.)

Supported cultures settings

Supported languages in App manifest

Different resource files in Solution Explorer

In a Windows Phone 7 project, you need to create culture references and resource files manually. First, check the languages you want to support – to do so, right-click the project name in Solution Explorer and choose “Properties” to show the project properties. Use the button on the right to open the Assembly Information and see which language is selected as Neutral Language. Now, you can add additional Languages by selecting them in the “Supported Cultures” list. No changes are necessary in the App Manifest.

Now, create on resource file for each language by choosing the “Resource File” option from the “Add New Item” dialog. The first resource file will be named “AppResources.resx” and contain the values in the Neutral Language, which we found out above. It is important that the Access Modifier for this resource file is set to “Internal” – if set to “No code generation”, the contained string values will not be automatically converted to properties and can therefore not be accessed from your code files!

Public access modifier in resource file

For all the additional supported languages, use the same filename but with culture suffix, e.g. “AppResources.de.resx” or “AppResources.de-DE.resx”.

Be sure to use the correct culture suffix when naming resource files! If you are unsure about the correct resource file naming (or experience problems, for example only the default language is used when running the App although the device settings are set to a different language), I recommend this blog post that reports a similar problem and covers the topic in detail.

(I’d like to note that creating localized resources for Windows Store Apps works similar to this procedure, although a different type of resource files (*.resw) is used and also assigning languages / cultures to the different resource files is somewhat different – for details on this topic, I recommend reading the relevant MSDN articles and one of the tutorials that can be found out there. However, if you plan to realize both a Windows Phone and a Windows Store App with the same functionality, sharing resources between those two projects might be an interesting option – in this case, check out Localization #3 and Localization #4!)

Using resources:

Now that your App knows which languages it will support and the necessary resource files are created and filled with string values, you’re ready to make use of those predefined string values and reference them in your App’s pages and / or code-behind!

Referencing string resources from a page’s code-behind (or from any other C#/VB code, e.g. from an MVVM Viewmodel) is easy. Depending on the currently selected device language, the appropriate resource file is selected automatically on App startup, and converted to a class AppResources which you can access from code. This class contains one property for each string value that you filled in, the names of these properties are equal to the string values’ keys. This means that to retrieve a localized string value with key “String1” and, for example, display it in a message box, simply do the following:

 
MessageBox.Show(AppResources.String1); 

However, in most cases you will need access to the resources from within XAML code, for example to fill user controls with localized content, add localized captions etc. For this, a separate resource provider class is needed, which is usually called LocalizedStrings. In Windows Phone 8 projects, such a class is generated automatically during project setup, and it looks as follows:

public class LocalizedStrings
{
	private static AppResources _localizedResources = new AppResources();
	public AppResources LocalizedResources { get { return _localizedResources; } }
}

For Windows Phone 7 projects, I recommend to simply create a LocalizedStrings class, e.g. in the solution’s root folder or inside some “Helpers” namespace, and copy-paste the code from the above listing to this class. The purpose of this class is to simply provide access to the global AppResources class we discussed above through a property.

Now, you can add this provider class as static resource in XAML code – either in each page that needs access to the localized string values, or simply in the App.xaml. If it does not yet exists, add the App’s local namespace to the header of the App.xaml file (assuming the LocalizedResources.cs is located in the “Helpers” namespace)

 
<Application x:Class="MyPhoneApp.App" ... xmlns:local="clr-namespace:MyPhoneApp.Helpers"> 

and add a reference to the LocalizedStrings class to the App’s resources:

<Application.Resources>
	<local:LocalizedStrings x:Key="LocalizedStrings"/>
</Application.Resources>

All pages can now use this resource to access the localized AppResoures. For example, to create a simple TextBlock with localized content:

 
<TextBlock Text="{Binding Source={StaticResource LocalizedStrings}, Path=LocalizedResources.String1}" /> 

Summary:

As described above, all that is needed for a basic localized App is a bunch of resource files, a provider class to enable access to these resources from within XAML code, and the correct registration of all supported languages in the App properties. Now, during startup the App checks which language is currently active on the phone and automatically chooses the appropriate resource file!

But what if your user would like to change the UI language from within the App? Check out my next blog post where I’ll present a simple solution to that question!