Localizing your Windows 8 apps – Part 1: Text

Reading Time: 3 minutes

Today, I gave my first MSDN webcast about how to localize a Windows 8 app. For those who missed it, and for the attendees that want to read what I was talking about, here is series of blog posts describing how to do it. You can also watch the session on Channel 9.

If you can’t wait and immediately want to dive in, or if you want to learn how to do this in HTML/JS, then take a look at this sample.

First of all: localizing an app is not hard or difficult. The hardest part is getting the design right if a text exceeds boundaries when it is displayed in another language. Let’s begin by localizing text on controls and in code.

When localizing text in XAML, you will have to assign a Uid to the controls. In XAML, the Uid property is in the xaml namespace, which typically has the prefix “x”; so to add the Uid, you’ll be using x:Uid="ControlUid".
You can freely choose the Uid, and it doesn’t have to be unique. For example, if you have a “Close” button appearing multiple times, you can assign a Uid named “CloseButton” and use that to provide a translation. This translation will then apply to all the different buttons with the Uid “CloseButton”. Also, you can leave your text or content in the XAML design. At run-time, your app will show the translated values instead of the ones specified at design-time.

XAML code example:

Now, to add translations, you’ll need a .resw file per language or culture that you want to localize your app in. I usually create a folder called Strings (and I’ve seen example apps doing the same thing) in which I’ll create subfolders per language. In my example, I’ve added a folder called “en” and one called “nl”, for English and Dutch resp. In each of these folders, I’ve then added a .resw file by right-clicking and selecting Add > New Item. You’ll find the Resources File item in the General tab.
When opening a resources file, you can add the Uid’s in this file and start overriding the properties per language:

  • For TextBlock and other pure text-based controls, you can add .Text to the Uid to change the text of the control.
  • For Buttons, you must use .Content to change the text.
  • For buttons in the AppBar that use a style based on AppBarButtonStyle, you must override the Name property of the AutomationProperties object.

For example:

AppTitle.Text My Application
A simple TextBlock control, so we override its Text property.
CancelButton.Content Cancel
A simple Button control, so we override its Content property.
NewFolderAppBarButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name New Folder
A button in an App Bar. Here, we must change the Name property of the AutomationProperties object (this is an attached property).

You can also override other properties, like Margin, Width, etc. if necessary, to adjust your layout when text grows larger or smaller. To override attached properties, like the AutomationProperties.Name, you’ll need to add the namespace of the class of the attached property inside your resources file.
During the talk, someone asked if this syntax is the same for VB.Net, or if it would become [Imports:namespace]:
for both C# and VB.Net, you must use the [using:namespace] notation.

When you want to translate strings used in code, like group headers or error messages, you’ll need to create an instance of the ResourceLoader class. If you named your resources file Resources.resw, then you don’t need to specify a name in the constructor. If you have a resources file called Errors.resw, to organize your error messages for instance, then you’ll need to pass “Errors” into the constructor when retrieving strings from that resources file.
To retrieve a string, use the GetString method and pass in the name of the string, like “ErrNoInternetConnection”.

Finally, you’ll need to set the default language for your application. If the user doesn’t have any of the languages supported by your app set in the control panel, Windows will use the default language of your application. To set this, open the Package.appxmanifest file and change the “Default language” setting on the “Application UI” tab.

You can download the code that I used when giving my talk here. This code demonstrates localizing text.

  • Naness

    I use a localization tool to localize resx files for eindows apps. You should write an article on such tools. The one I use is https://poeditor.com and it works really nice, with a simple interface and a good translation memory to help out.