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.
Tip
The Multilingual App Toolkit, which integrates with Visual Studio Professional 2012 and Visual Studio Express 2012 for Windows Phone, provides translation support, translation file management, and localization tools to create Windows Phone apps and Windows Store apps. Use this toolkit to connect with the Microsoft Translator for quick translation suggestions. For more information, see How to use the Multilingual App Toolkit.
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
Create a Windows Phone application project.
Open and view the file named MainPage.xaml.
Locate the StackPanel element named TitlePanel.
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.
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"/>In the AppResources.resx file, create a new string resource named “PageTitle” with the value that applies to your app.
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"/>To localize your app’s ApplicationBar, in the MainPage.xaml.cs file, uncomment the BuildLocalizedApplicationBar method call and function.
Replace the values of the AppBarMenuItemText and AppBarButtonText resources in the AppResources.resx file.
Add buttons, menu items, and associated resources that you would like to use in your app.
To add additional languages
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.
Save the project.
Note
Visual Studio has created a new resource file for each supported language that is a copy of the neutral resource file (AppResources.resx) and renamed it to include the locale code that reflects the new resource file’s Culture.
- Replace the neutral language values in each supported language resource file with translated values.
Warning
To insure that the correct description of the localized languages for your app will be seen by users in the Windows Phone Store, use the following practices: If you need to remove a Supported Culture that you have added (by clearing the selection in the list in Project Properties) be sure to remove the associated Supported Language in WMAppManifest.xml (using the list in Manifest Designer > Supported Language > Packaging). Also, ensure that you understand the impact before modifying the Supported Languages list or Default Language in WMAppManifest.xml.
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.
Warning
The following code example is included in each relevant template, but is reproduced in the Globalization Sample.
// 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.