In this lesson I'll explain how to localize your app ... that simply means that we can
present the various bits of text in your app in different languages. For example, I may
want to support both English speakers and Spanish speakers opening up the number of markets I could potentially sell my app in. Now, there's a bit more to selling in different
markets than merely localizing my app, however this would be a big step in the right
direction.
Our game plan in this lesson:
1. We'l learn about the AppResources.resx file, and how it allows us to store name/ value pairs that we can access in our declarative XAML code (or imperative C# code).
2. We'l see how to create language and region specific variations of the file in Visual Studio.
3. We'l learn how the Windows Phone 8 Operating System wil choose the correct version of our AppResources.resx file based on the user's language and region.
1. Modify the AppResources.resx settings and bind to its values
If you expand the Resource folder of our PetSounds project, you'll see a file called
AppResources.resx:
If you double-click to open it, it will open with a special designer in the main area:
This file is a series of Name / Value pairs. On the left are names of settings we will bind to. On the right, the settings for a given language. Which language? See the very last attribute:
ResourceLanguage
... is set to ...
en-US
"en" means "English". "US" is the region and in this case means "USA". Therefore, these settings should be used in the USA for English speakers. It's also the default AppResources file (you'll see the difference between the default and other languages / regions we support in just a moment).
The Name / Value pairs are mostly snippets of text we'll use throughout the app.
However, the "ResourceFlowDirection" is a setting for which direction the characters should be presented. As you know, some languages are read from RightToLeft and this setting would be used throughout the app for this purpose.
As you can see, there's an ApplicationTitle setting set to "MY APPLICATION". What if I wanted to convert the TextBlock on our MainPage.xaml to utilize the AppResources setting? I would use a binding expression like so:
As you can see, I've replaced the hardcoded text to this binding expression:
Text="{Binding Path=LocalizedResources.ApplicationTitle,Source= StaticResource LocalizedStrings}}"
There's several things at work here that would require a lot of background explanation.
For now, just know we're using a binding expression to bind data to an attribute, the Text. The Path attribute of the binding expression refers to the LocalizedStrings.cs file in our project. It creates an instance of an AppResources object which provides us access to the appropriate AppResources file based on the region and preferred language of the
Phone's user. We'll see it all come together in a bit. The .ApplicationTitle references the specific Name entry in the AppResources.resx file. The Source attribute is bound to LocalizedStrings ... again, that's where the compiler can find the source of the LocalizedResources property ... it's part of the LocalizedStrings class in the LocalizedStrings.cs file.
For a more in-depth discussion of how all these ideas interrelate, I would encourage you to check our a great article on MSDN:
2. Add support for a second language
At this point, we're only supporting English (in the USA). I would like to support the Spanish language no matter which region of the world the user resides. To do that ...
1. In the Solution Explorer, right-click on the Project title PetSounds
2. Select "Properties" from the context-menu
The Project Properties designer appears with the Application tab on the right already selected (if it's not, select it!)
Under "Supported Cultures", place a checkmark next to "Spanish".
Next, save the project and CLOSE the Project Properties tab. It's possible you will see the following message (depending on what you currently have loaded into the main area of Visual Studio):
If you see this, you can click the "Yes" button.
Now, in the Resources folder, you should see a new, second file appear:
AppResources.es.resx
The .es suffix to the AppResources file indicates the language, Spanish (es for
"Espanol"). Double-click that file to open it in the main area:
By default, it's in English. With my son's help—he'sa third-year high school Spanish student—I translated the Values from English to Spanish. NOTE: The Names MUST BE IDENTICAL IN BOTH THE ENGLISH AND SPANISH VERSIONS OF THIS FILE. Do not translate the Names ... only the Values! The Names are tokens used programmatically. The values will be displayed to the end user:
3. Test the different language version of the app After I've completed the translations, run the app (F5) and use the Phone Emulators' Start button, then I swipe to the alphabetical listing of apps, and scroll down the to the Settings app and tap to open it:
On the "system" page of the Settings app, I scroll down to "language+region" and tap that option:
On the "language+region" page, I change the click the Phone Language to edit it from "English (United States)" ...
... and in the list of languages and regions, I select "espanol (Espana)":
I then scroll to the bottom of the page to see the "restart phone" button. Note the
message that says "restart required":
When I restart, I see the message "hasta luego":
At this point Visual Studio may disconnect ... that's ok, you don't need to be in Debug Mode in Visual Studio ... just focus on the Phone Emulator for now. The Phone Emulator will use the last deployed version of the app.
Once the Phone Emulator reboots, you can swipe over to the list of apps to see that they are all in Spanish.
Tap the "PetSounds" app ...
... and when the app opens, you can see the Title has been replaced with the title we entered in the AppResources.es.resx file.
Outstanding! Now, I would simply need to repeat these steps ... especially about
creating Name / Value pairs and using binding expressions throughout the app in order to completely localize the app's user interface.
Unless you're bilingual, you'll probably want to re-trace your steps and reset the Phone Emulator to use English. Alternatively, you can completely shut down the Phone Emulator (in the Windows task bar, right-click, select Close) and Visual Studio will re-start the Phone Emulator with the default settings.
Recap
To recap, the big takeaway in this lesson was how to localize your app using
AppResources files, the Project Properties, and some binding syntax. We saw how we could set the language and region of our phone to test our localization customizations as well.
No comments:
Post a Comment