688 CHAPTER 21: Application Localization

/* Used to ask the user's birth date */ "Birthday" = "Anniversaire";

The Localized String Macro

You won’t actually create the strings file by hand. Instead, you’ll embed each localizable text string in a special macro in your code. Once your source code is final and ready for localization, you’ll run a command-line program, named genstrings, which will search all your code files for occurrences of the macro, pulling out all the unique strings and embedding them in a localizable strings file.

Let’s see how the macro works. First, here’s a traditional string declaration:

NSString *myString = @"First Name";

To make this string localizable, do this instead:

NSString *myString = NSLocalizedString(@"First Name", @"Used to ask the user his/her first name");

The NSLocalizedString macro takes two parameters:

The first parameter is the string value in the base language. If there is no localization, the application will use this string.

The second parameter is used as a comment in the strings file.

NSLocalizedString looks in the application bundle inside the appropriate localization project for a strings file named localizable.strings. If it does not find the file, it returns its first parameter, and the string will appear in the development base language. Strings are typically displayed only in the base language during development, since the application will not yet be localized.

If NSLocalizedString finds the strings file, it searches the file for a line that matches the first parameter. In the preceding example, NSLocalizedString will search the strings file for the string "First Name". If it doesn’t find a match in the localization project that matches the user’s language settings, it will then look for a strings file in the base language and use the value there. If there is no strings file, it will just use the first parameter you passed to the NSLocalizedString macro.

Now that you have an idea of how the localization architecture and the strings file work, let’s take a look at localization in action.

Real-World iOS: Localizing Your Application

We’re going to create a small application that displays the user’s current locale. A locale (an instance of NSLocale) represents both the user’s language and region. It is used by the system to determine which language to use when interacting with the user, as well as how to display dates, currency, and time information, among other things. After we create the application, we will then localize it into other languages. You’ll learn how to localize nib files, strings files, images, and even your application’s display name.

www.it-ebooks.info

CHAPTER 21: Application Localization

689

You can see what our application is going to look like in Figure 21–1. The name across the top comes from the user’s locale. The words down the left side of the view are static labels that are set in the nib file. The words down the right side are set programmatically using outlets. The flag image at the bottom of the screen is a static UIImageView.

Figure 21–1. The LocalizeMe application shown with two different language/region settings

Let’s hop right into it.

Setting Up LocalizeMe

Create a new project in Xcode using the Single View Application template, and call it

LocalizeMe.

If you look in the source code archive, within the 21 - LocalizeMe folder, you’ll see a folder named Images. Inside that folder, you’ll find a pair of folders, one named English and one named French, each containing a file named flag.png. One version of the flag is the US flag, and the other is the French flag.

Start by dragging the English language version of flag.png into the project navigator’s LocalizeMe folder. When prompted, add a copy of that file to the project. We’ll get to the French version of that file as we make our way through the chapter.

www.it-ebooks.info

690	CHAPTER 21: Application Localization

Now let’s add some label outlets to the project. We need to create outlets to a total of six labels: one for the blue title across the top of the view, and five for the words down the right-hand side (see Figure 21–1). Select BIDViewController.h, and make the following changes:

#import <UIKit/UIKit.h>

@interface BIDViewController : UIViewController

@property (weak, nonatomic) IBOutlet UILabel *localeLabel; @property (weak, nonatomic) IBOutlet UILabel *label1; @property (weak, nonatomic) IBOutlet UILabel *label2; @property (weak, nonatomic) IBOutlet UILabel *label3; @property (weak, nonatomic) IBOutlet UILabel *label4; @property (weak, nonatomic) IBOutlet UILabel *label5;

@end

Now select the BIDViewController.xib file to edit the GUI in Interface Builder. Make sure the View window is visible, and then drag a Label from the library, dropping it at the top of the view, aligned with the top blue guideline. Resize the label so that it takes the entire width of the view, from blue guideline to blue guideline. With the label selected, open the attributes inspector. Look for the Font control, and click the small T icon it contains to bring up a small font-selection popup. Click System Bold to let this title label stand out a bit from the rest. Then use the attributes inspector to set the text alignment to centered, and set the text color to a bright blue. You can also use the font selector to make the font size larger if you wish. As long as Autoshrink is selected in the object attributes inspector, the text will be resized if it gets too long to fit.

With your label in place, control-drag from the File’s Owner icon to this new label, and select the localeLabel outlet.

Next, drag five more Labels from the library, and put them against the left margin using the blue guideline, one above the other (see Figure 21–1). Resize the labels so they go about halfway across the view, or a little less. Double-click the top one, and change it from Label to One. Repeat this procedure with the other four labels, changing the text to the numbers Two through Five.

Drag five more Labels from the library, this time placing them against the right margin. Change the text alignment using the object attributes inspector so that they are rightaligned, and increase the size of the label so that it stretches from the right blue guideline to about the middle of the view. Control-drag from File’s Owner to each of the five new labels, connecting each one to a different numbered label outlet. Now, doubleclick each one of the new labels, and delete its text. We will be setting these values programmatically.

Finally, drag an Image View from the library over to the bottom part of the view so it touches the bottom and left blue guidelines. In the attributes inspector, select flag.png for the view’s Image attribute, and resize the image to stretch from blue guideline to blue guideline. In the attributes inspector, change the Mode attribute from its current value to Aspect Fit. Not all flags have the same aspect ratio, and we want to make sure the localized versions of the image look right. Selecting this option will cause the image view

www.it-ebooks.info

CHAPTER 21: Application Localization

691

to resize any other images put in this image view so they fit, but it will maintain the correct aspect ratio (ratio of height to width). Finally, make the flag bigger, until it hits the right-side blue guideline.

Save your nib. Then switch to BIDViewController.m, and insert the following code at the top of the file:

#import "BIDViewController.h"

@implementation BIDViewController

@synthesize localeLabel; @synthesize label1; @synthesize label2; @synthesize label3; @synthesize label4; @synthesize label5;

.

.

.

Now, provide the following implementation for the viewDidLoad method:

- (void)viewDidLoad

{

[super viewDidLoad];

// Do any additional setup after loading the view, typically from a nib.

NSLocale *locale = [NSLocale currentLocale]; NSString *displayNameString = [locale

displayNameForKey:NSLocaleIdentifier value:[locale localeIdentifier]];

localeLabel.text = displayNameString;

label1.text = NSLocalizedString(@"One", @"The number 1"); label2.text = NSLocalizedString(@"Two", @"The number 2"); label3.text = NSLocalizedString(@"Three", @"The number 3"); label4.text = NSLocalizedString(@"Four", @"The number 4"); label5.text = NSLocalizedString(@"Five", @"The number 5");

}

Also, add the following code to the existing viewDidUnload method:

- (void)viewDidUnload

{

[super viewDidUnload];

//Release any retained subviews of the main view.

//e.g. self.myOutlet = nil;

self.localeLabel = nil; self.label1 = nil; self.label2 = nil; self.label3 = nil; self.label4 = nil; self.label5 = nil;

}

www.it-ebooks.info

692	CHAPTER 21: Application Localization

The only item of note in this class is the viewDidLoad method. The first thing we do there is get an NSLocale instance that represents the user’s current locale, which can tell us both the user’s language and region preferences, as set in the iPhone’s Settings application.

NSLocale *locale = [NSLocale currentLocale];

The next line of code might need a bit of explanation. NSLocale works somewhat like a dictionary. It can give you a whole bunch of information about the current user’s preferences, including the name of the currency and the expected date format. You can find a complete list of the information that you can retrieve in the NSLocale API reference.

In this next line of code, we’re retrieving the locale identifier, which is the name of the language and/or region that this locale represents. We’re using a function called displayNameForKey:value:. The purpose of this method is to return the value of the item we’ve requested in a specific language.

The display name for the French language, for example, is Français in French, but French in English. This method gives you the ability to retrieve data about any locale so that it can be displayed appropriately to any users. In this case, we’re getting the display name for the locale in the language of that locale, which is why we pass [locale localeIdentifier] in the second argument. The localeIdentifier is a string in the format we used earlier to create our language projects. For an American English speaker, it would be en_US, and for a French speaker from France, it would be fr_FR.

NSString *displayNameString = [locale displayNameForKey:NSLocaleIdentifier value:[locale localeIdentifier]];

Once we have the display name, we use it to set the top label in the view.

localeLabel.text = displayNameString;

Next, we set the five other labels to the numbers one through five spelled out in our development base language. We also provide a comment telling what each word is. You can just pass an empty string if the words are obvious, as they are here, but any string you pass in the second argument will be turned into a comment in the strings file, so you can use this comment to communicate with the person doing your translations.

label1.text = NSLocalizedString(@"One", @"The number 1"); label2.text = NSLocalizedString(@"Two", @"The number 2"); label3.text = NSLocalizedString(@"Three", @"The number 3"); label4.text = NSLocalizedString(@"Four", @"The number 4"); label5.text = NSLocalizedString(@"Five", @"The number 5");

Let’s run our application now.

www.it-ebooks.info