How to build a localized app for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes how to separate localizable resources from code by using language-specific resource files. Visual Studio uses these resource files to create assemblies through which your app can support many languages. For more info about this process, see Packaging and Deploying Resources.

To view a full, working code sample that contains all of the following code examples, download the Globalization Sample.

For additional info about making your app localizable, see Localization best practices for Windows Phone 8.

This topic contains the following sections.

• Localizing your app
• Localizing the app bar
• Testing a localized app
• Related Topics

Localizing your app

As described in Localization best practices for Windows Phone 8, it’s important to separate your code from your localizable resources. A common practice for localizing an app’s UI text strings is to copy each string to a row in a resource file's string table. Each original string is then replaced with a binding statement (XAML) or resource reference (code-behind) that points to the corresponding resource in that table.

The initial resource file you use to capture UI strings that are being localized is called AppResources.resx and is created in the app’s Resources folder by default when your project is created. AppResources.resx is also called the neutral language resource. It’s initialized with placeholder string resources and values for the template’s UI text XAML elements, and with sample code for localizing the app bar, where appropriate.

Each culture that your app supports has its own resource file, with string resources that match those in AppResources.resx but whose values will be localized. These files are created when you add a Supported Culture and name using the locale code of their culture, such as AppResources.en-US.resx.

When launched, your localized app will implicitly load and display the resources with the culture that most closely matches the user’s phone display language choice. If no good match exists, the neutral language resources will be used by the app. App code can explicitly override the implicit culture selection per element or globally.

Replacing hard-coded strings with strings from a resource file

1. Create a Windows Phone application project.

2. Open and view the file named MainPage.xaml.

3. Locate the StackPanel element named TitlePanel.

4. Replace the hard-coded value “MY APPLICATION” in the Text attribute of the first TextBlock with the following binding clause for the resource “ApplicationTitle”:

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

   The “ApplicationTitle” resource exists in the AppResources.resx file by default.

5. Replace the value of "ApplicationTitle" in the AppResources.resx file with the name of your app.

   The TextBlock element will now be the following:

   <TextBlock Text="{Binding Path=LocalizedResources.ApplicationTitle, Source={StaticResource LocalizedStrings}}" 
       Style="{StaticResource PhoneTextNormalStyle}" Margin="12,0"/>
   

6. In the AppResources.resx file, create a new string resource named “PageTitle” with the value that applies to your app.

7. In MainPage.xaml, replace the hard-coded value “page name” in the Text attribute of the second TextBlock with the binding clause for the resource “PageTitle”.

   The TextBlock element will now be the following:

   <TextBlock Text="{Binding Path=LocalizedResources.PageTitle, Source={StaticResource LocalizedStrings}}" 
       Style="{StaticResource PhoneTextNormalStyle}" Margin="12,0"/>
   

8. To localize your app’s ApplicationBar, in the MainPage.xaml.cs file, uncomment the BuildLocalizedApplicationBar method call and function.

9. Replace the values of the AppBarMenuItemText and AppBarButtonText resources in the AppResources.resx file.

10. Add buttons, menu items, and associated resources that you would like to use in your app.

To add additional languages

1. After you have created and tested your app using a neutral language, you can add supported languages.

   On the project’s Properties page, in the Supported Culture box, select the language(s) you would like your app to support.

2. Save the project.

3. Replace the neutral language values in each supported language resource file with translated values.

Localizing the app bar

You can add an app bar to a page in your app either in the page XAML or using C# in the page code-behind. However, the XAML app bar doesn’t support dynamic data binding for the text label of the ApplicationBarIconButton or for the text of the ApplicationBarMenuItem. For this reason, the following code, along with a call to it in the MainPage constructor and placeholder resources, are reproduced as commented samples in each relevant New Project template. For info about creating an app bar, see App bar for Windows Phone.

// Build a localized ApplicationBar
private void BuildLocalizedApplicationBar()
{
    // Set the page's ApplicationBar to a new instance of ApplicationBar.
    ApplicationBar = new ApplicationBar();

    // Create a new button and set the text value to the localized string from AppResources.
    ApplicationBarIconButton appBarButton = 
        new ApplicationBarIconButton(new   
        Uri("/Assets/AppBar/appbar.add.rest.png", UriKind.Relative));
        appBarButton.Text = AppResources.AppBarButtonText;
    ApplicationBar.Buttons.Add(appBarButton);

    // Create a new menu item with the localized string from AppResources.
    ApplicationBarMenuItem appBarMenuItem = 
        new ApplicationBarMenuItem(AppResources.AppBarMenuItemText);
    ApplicationBar.MenuItems.Add(appBarMenuItem);
}

Testing a localized app

To test your localized strings, follow the steps in How to test a localized app for Windows Phone 8.

See Also

Other Resources

Globalization and localization for Windows Phone 8