Working With App Resources on Windows Phone

In previous tutorials, we learned about application resources, the MAT (Multilingual App Toolkit), and how to test a localized app. In this tutorial, we will not only sum it all up in an easier way, but also create a localized application bar that you can use anywhere in your application.

Developers often have to use the same application bar on several pages in their project and they usually end up copying and pasting the XAML and C# code, which isn't recommended.

In this tutorial, you will learn how to use app resources and how to add localization and globalization to your apps. You will also learn to use the App.xaml and App.xaml.cs files to build a localized application bar that you can use anywhere in your Windows Phone app.

1. Why Build a Localized App?

Windows Phone users are not all native English speakers. In fact, only 34% of them speak English. This means that 66% speak a language other than English and that is why it's important to build localized apps.

One effective strategy to increase app downloads is by making your app more suitable for Windows Phone customers that don't speak English. The more languages your app supports, the more downloads it will get and the better the ratings of your app will be. By supporting French, German, Arabic, and Spanish, you support about 75% of the Windows Phone market.

In this tutorial, we will be translating all of our app resources into French and Arabic. Here are some quick tips to keep in mind before we start:

• Make sure to name all the resources you'll be using with meaningfulnames, because we will be referring to string resources by their name, not their value. Try to give each resource a unique name that makes sense.
• Try to gather all of your string resources in AppResources.resx, including button titles and error messages.
• Enable multiline support and text wrap in controls.
• Always save your work and make sure to rebuild your project often to implement the changes you make to AppResources.resx.

2. Culture & Language Support

Currencies, numbers, date, time, and region formats differ from culture to culture. Fortunately, the CultureInfo class takes care of these details for each language. Actually, you can even retrieve the current cultural data of the phone and show its information in a MessageBox using a single line of code:

MessageBox.Show(CultureInfo.CurrentCulture.Name);

However, the InitializeLanguage() function in App.xaml.cs does the work automatically each time the app is launched and sets RootFrame.Language based on the value of the AppResources.ResourceLanguage resource. Note that if your app doesn't support any language other than en-US (English, United States), the app uses the neutral and default AppResources.resx file of the project.

3. Localizing Your App

Step 1: Adding Resources and Binding Text Elements

In this tutorial, we will build a one-page app that will show the user some wise, old sayings. To start, in MainPage.xaml, we'll add a few TextBlock elements without specifying their content by adding the following two lines of code in the parent ContentPanel grid:

<TextBlock TextWrapping="Wrap" FontSize="30"></TextBlock><TextBlock TextWrapping="Wrap" FontSize="30"></TextBlock>

We also make the following changes in the default AppResources.resx file:

• changing the ApplicationTitle string value
• adding two strings as shown in the following screenshot

Let's now go back to MainPage.xaml. After adding the strings we'll need in our app, we set the Text property of the TextBlock control to specify the contentof each TextBlock.

Instead of showing "MY APPLICATION" as the title, we use the string "My Localized App". We can accomplish this by using a binding that makes the reference to the app resources, binding the value of the string. To make this reference, we won't be using the string value itself but its attribute(name), ApplicationTitle.

Text="{Binding Path=LocalizedResources.ApplicationTitle, Source={StaticResource LocalizedStrings}}"

Each of the two TextBlock elements will have a saying as well. We'll just use the same line of code, replacing the ApplicationTitle attribute with our saying's attribute. This is what your code should look like:

<StackPanel><TextBlock TextWrapping="Wrap" Text="{Binding Path=LocalizedResources.HappinessSaying, Source={StaticResource LocalizedStrings}}" FontSize="30"></TextBlock><TextBlock TextWrapping="Wrap" Text="{Binding Path=LocalizedResources.NelsonMandelaSaying, Source={StaticResource LocalizedStrings}}" FontSize="30"></TextBlock></StackPanel>

This is what the result looks like:

We now only need to add other languages and translate.

Step 2: Adding Other Languages

To add another language, go to the project's properties by right-clicking the project in the Solution Explorer window. Make sure to access the project's properties, not the properties of the solution.

In the Application Tab you should see the Supported Languages section. Select the language that you want to support. As mentioned earlier in this tutorial, we will add French and Arabic. As you can see in the list, you can even select the culture depending on the region, such as French (France), French (Belgium). For this tutorial, we'll just choose the general one, ignoring dialect and region.

Once you save the changes, you'll notice that Visual Studio has automatically generated two new .resx files:

• AppResources.ar.resx for Arabic
• AppResources.fr.resx for French

Note that the newly generated files have the same content as AppResources.resx. You shouldn't change the attributes (names). You only need to translate the values.

3. Using the Multilingual App Toolkit

The Multilingual App Toolkit is very helpful for translating string resources. It is integrated into Visual Studio, providing support for building localized Windows and Windows Phone apps, and helping with translating app resources. The Multilingual App Toolkit makes adding other languages easier and you can import and export translation files easily.

You can download the Multilingual App Toolkit as a Visual Studio extension from Microsoft's developer website. After installing the toolkit, select Enable Multilingual App Toolkit from the Tools menu.

After enabling the MAT, Visual Studio generates new .xlf files for each of the supported languages you added earlier. This means that you can generate machine translations by right-clicking an .xlf file and choosing Generate machine translations. You can also modify the translated string resources in the target tag in all the .xlf files.

4. How to Test a Localized App?

You can test a localized app using the emulator.

• Debug your project and go to Emulator Settings.
• Navigate to the Language tab and add a new language. It's important to not restart your phone.
  
• Navigate to the Region tab and choose your region.
  
• Restart the phone.
  

When the phone restarts, Visual Studio may throw an error, losing the connection with the emulator.  After restarting the phone, debug the project again. This is what the app looks like for Arabic:

Now that we're done with string resources, we'll add a localized application bar to our app.

5. Creating a Localized Application Bar

Step 1: Creating the Application Bar

In this step, we'll create an application bar that we can use anywhere in our app. To do so, we'll make use of the App.xaml file, in which we define global XAML styles and resources that will be used across the application.

In the ApplicationResources tag in App.xaml, we add an application bar with only an icon and a menu item. Don't forget to give a nameto the application bar using the x:key attribute so that we can reference it later.

<shell:ApplicationBar x:Key="myAppBar" IsVisible="True" IsMenuEnabled="True" ><shell:ApplicationBarIconButton IconUri="/Assets/AppBar/questionmark.png" Text="test" Click="Help_Click" /><shell:ApplicationBar.MenuItems><shell:ApplicationBarMenuItem Text="Rate and review" Click="RateReview_Click" /></shell:ApplicationBar.MenuItems></shell:ApplicationBar>

In the RateReview_Click event handler, we use one of the phone tasks to navigate users to the store if they want to leave a review or rate the app. As for the Help_Click event handler, we just add some C# code to navigate between the different pages. Note that I added a new XAML page, AboutTheApp.xaml, in which we show information about our app.

In App.xamls.cs, add the following statement so that we can benefit from the phone tasks class:

using Microsoft.Phone.Shell;

When the user taps the rate and review menu item, the app will open the store on a page where the user can rate and/or review the app. We use a MarketPlaceReviewTask like this:

MarketplaceReviewTask review = new MarketplaceReviewTask();
review.Show();

As for the Help_Click event handler, the following code snippet takes care of navigating between the two pages:

(Application.Current.RootVisual as PhoneApplicationFrame).Navigate(new Uri("/AboutTheApp.xaml", UriKind.RelativeOrAbsolute));

Step 2: Referencing the Application Bar

After creating the application bar that we want to use, we add a new instance of the application bar using the below code snippet in MainPage.xaml.cs and then we make it refer to the one in App.xaml.

InitializeComponent();
ApplicationBar = new ApplicationBar();
ApplicationBar = ((ApplicationBar)Application.Current.Resources["myAppBar"]);

We haven't used the AppResources at all for building the application bar, which means that text properties are already set independently from the phone's culture. Actually, we can't really use bindings when dealing with application bars.

This is why we'll reference the application bar we created earlier in App.xaml.cs and change the strings value, using a simple block of a code just after the InitializeComponent() method. The strings used are also added to AppResources.resx.

// Standard XAML initialization
InitializeComponent();
var appBar = App.Current.Resources["myAppBar"] as ApplicationBar;
((ApplicationBarIconButton)appBar.Buttons[0]).Text = AppResources.AboutAppBarIconText;
((ApplicationBarMenuItem)appBar.MenuItems[0]).Text = AppResources.RateAppBarMenuItemText;

After adding the string resources, translate them and rebuild the project. Finally, add the information of the AboutTheApp.xaml page. This is what the result looks like:

Conclusion

In this tutorial, we learned about phone culture, how to use app resources, how to build a localized application and application bar, and how to build an app bar that we can reuse anywhere in our application. We also learned how to make a reference to a string value in the AppResources files using bindings.

And finally, we got to know the way we use phone tasks to help users rate and review the app in the store. Feel free to download the sample project and ask any question that crosses your mind in the comments below.