You won't actually create the strings file by hand. Instead, you'll embed all localizable text strings 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.

Here's how the macro works. Let's start with a traditional string declaration:

NSString *myString = @"First Name";

To make this string localizable, you'll 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 is the string value in the base language. If there is no localization, the application will use this string. The second parameter will be 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.

Let's take a look at this process in action.

The next line of code might need a little bit of explanation. NSLocale works somewhat like a dictionary. There is a whole bunch of information that it can give us about the current users' preferences, including the name of the currency they use and the date format they expect. 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, would be Français in French, but French in English. This method gives us 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 in [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. You can use either the simulator or a device to test this. The simulator does seem to cache some language and region settings, so you may want to do this on the device if you have that option. Once the application launches, it should look like Figure 17-2.

By using the NSLocalizedString macros instead of static strings, we are all ready for localization. But we are not localized yet. If you use the Settings application on the simulator or on your iPhone to change to another language or region, the results would look essentially the same, except for the label at the top of the view (see Figure 17-3).

Figure 17.2. The language running under the authors' base language. Our application is set up for localization but is not yet localized.

Figure 17.3. The nonlocalized application run on an iPhone set to use the French language

Now, let's localize the nib file. The basic process for localizing any file is the same. In Xcode, single-click LocalizeMeViewController.xib, and then press

Figure 17.4. The LocalizeMeViewController.xib Info window

When you click the Make File Localizable button, the window will switch to the Targets tab. Close the Info window, and look at the Groups & Files pane in Xcode. Notice that the LocalizeMeViewController.xib file now has a disclosure triangle next to it, as if it were a group or folder. Expand it, and take a look (see Figure 17-5).

Figure 17.5. Localizable files have a disclosure triangle and a child value for each language or region you add.

In our project, LocalizeMeViewController.xib has one child, English. This one was created automatically, and it represents your development base language. Go to the Finder, and open your LocalizeMe project folder. You should see a new folder named English.lproj (see Figure 17-6).

Figure 17.6. By making a file localizable, Xcode created a language project folder for our base language.

At the time of this writing, Xcode is still using the legacy project name for the development base language project, English.lproj, rather than following Apple's localization convention of using the ISO two-letter language code, which would have resulted in a folder called en.lproj instead. This is listed in the Xcode 3.1 release notes as a known issue. You don't need to change this folder name, as it will work just fine, but use the ISO codes for any new localizations you add.

Single-click LocalizeMeViewController.xib in the Groups & Files pane again, and press

After you press return, Xcode will create a new localization project in your project folder called fr.lproj and copy LocalizeMeViewController.xib there. In the Groups & Files pane, LocalizeMeViewController.xib should now have two children, English and fr. Double-click fr to open the nib file that will be shown to French speakers.

The nib file that opens in Interface Builder will look exactly like the one you built earlier, because the nib file you just created is a copy of the earlier one. Any changes you make to this one will be shown to people who speak French, so double-click each of the labels on the left side and change them from One, Two, Three, Four, Five to Un, Deux, Trois, Quatre, Cinq. Once you have changed them, save the nib, and go back to Xcode. Your nib is now localized in to French. Compile and run the program. After it launches, tap the home button.

iPhone caches settings, so if we were to just go and run the application now, there's a very good chance we would see exactly what we saw before. In order to make sure we see the correct thing, we need to go reset the simulator and do a clean build of our application.

On the simulator, there's a menu option under the iPhone Simulator menu to Reset Content and Settings.... Select that now. After you select it, you should be presented with the home screen. From there, go to the Settings application, and select the General row and then the row labeled International. From here, you'll be able to change your language and region preferences (see Figure 17-7).

Figure 17.7. Changing the language and region, the two settings that affect the user's locale

Change the Region Format from United States to France (which is under the row for French), and then change Language from English to Français. Now click the Done button. And finally, quit the simulator, and go to Xcode. You want to change the Region Format first, because once you change the language, your iPhone will reset and go back to the home screen. Now, your phone is set to use French.

Back in Xcode, and select Clean from the Build menu. Make sure all the checkboxes on the presented sheet are checked, and then click the Clean button. This will remove all traces of the previous build. Once the clean operation is done, build and run LocalizeMe again. This time, the words down the left-hand side should show up in French (see Figure 17-8).

The problem is that the flag and right column of text are still wrong. We'll take care of the flag first. Now, we could have changed the flag image right in the nib by just selecting a different image for the image view in the French localized nib file. Instead of doing that, we'll actually localize the flag image itself. When an image or other resource used by a nib is localized, the nib will automatically show the correct version for the language, though not for the dialect, at the time of this writing. If we localize the flag.png file itself with a French version, the nib will automatically show the correct flag when appropriate.

Figure 17.8. The application is partially translated into French now.

Let's localize the flag image now. Single-click flag.png in Xcode's Groups & Files pane. Next, press

That's it. You're done. If you are running in the simulator, reset the simulator and do a clean build, as you did earlier before rerunning the program. Once you rerun, you'll need to reset the region and language to get the French flag to appear.

If you're running on the device, your iPhone has probably cached the American flag from the last time you ran the application, let's remove the old application from your iPhone using the Organizer window in Xcode.

Select Organizer from the Window menu, or press ^

Figure 17.9. The Xcode Organizer window lets you manually remove applications.

On the Summary tab, you'll see three sections. The bottommost section is labeled Applications. In the list of applications, look for LocalizeMe; select it, and click the minus button to remove the old version of that application and the caches associated with it.

Now, select Clean from the Build menu, and build and run the application again. Once the application launches, you'll need to reset the region then the language and the French flag should now come up in addition to the French words down the left-hand side (see Figure 17-10).

Figure 17.10. The image and nib are both localized now.

You can localize the application's icon image in exactly the same way that you localized flag.png. Single-click icon.png in the Groups & Files pane's Resources group. Bring up the Info window, and switch to the General tab if you're not already there. Click the Make File Localizable button, and switch back to the General tab. Click the Add Localization button, and when prompted for the language, type fr.

In the fr folder in the Resources folder of 17 LocalizeMe, where you just copied the flag.png file, you'll also find a localized version of icon.png. Copy that into your fr.lproj folder using the Finder, overwriting the version that's there. Now, the iPhone will automatically detect and show this icon to users who speak French, though you'll probably need to delete the application from your phone again, or reset the simulator to get the change to show up.

If you look at Figure 17-10, you'll see that the words on the right-hand side of the view are still in English. In order to translate those, we need to generate our base language strings file and then localize that. In order to accomplish this, we'll need to leave the comfy confines of Xcode for a few minutes.

Figure 17.11. We localized our application icon!

Launch Terminal.app, which is in /Applications/Utilities/. When the terminal window opens, type cd followed by a space. Don't press return.

Now, go to the Finder, and drag your LocalizeMe project folder to the terminal window. As soon as you drop the folder onto the terminal window, the path to the project folder should appear on the command line. Now, press return.

The cd command is Unix-speak for "change directory," so what you've just done is steer your terminal session from its default directory over to your project directory.

Our next step is to run the program genstrings and tell it to find all the occurrences of NSLocalizedString in our .m files in the Classes folder. To do this, type the following command, and then press return:

genstrings ./Classes/*.m

When the command is done executing (it just takes a second on a project this small) you'll be returned to the command line. In the Finder, look in the project folder for a new file called Localizable.strings. Drag that to the Resources folder in Xcode's Groups & Files pane, but when it prompts you, don't click the Add button just yet.

Localizable.strings files are encoded in UTF-16, which is a two-byte version of Unicode. Most of us are probably using UTF-8 or a language-local encoding scheme as our default encoding in Xcode. When we import the Localizable.strings file into our project, we need to take that into account. First, uncheck the box that says Copy items into destination group's folder (if needed), because the file is already in our project folder. More importantly, change the text encoding to Unicode (UTF-16) (see Figure 17-12). If you don't do that, the file will look like gibberish when you try to edit it in Xcode.

Figure 17.12. Importing the Localizable.strings file

Now, go ahead and click the Add button. Once the file is imported, single-click Localizable.strings in Resources, and take a look at it. It should contain five entries, because we use NSLocalizableString five times with five distinct values. The values that we passed in as the second argument have become the comments for each of the strings.

The strings were generated in alphabetical order, which is a nice feature. In this case, since we're dealing with numbers, alphabetical order is not the most intuitive way to present them, but in most cases, having them in alphabetical order will be helpful.

/* The number 5 */
"Five" = "Five";

/* The number 4 */
"Four" = "Four";

/* The number 1 */
"One" = "One";

/* The number 3 */
"Three" = "Three";

/* The number 2 */
"Two" = "Two";

Let's localize this sucker.

Single-click Localizable.strings, and press

Switch back to the General tab, and click Add Localization. When prompted for a language, type fr to indicate that we are localizing for all dialects of the French language. Back in the Groups & Files pane of Xcode, click the disclosure triangle next to Localizable.strings. Single-click fr, and in the editor pane of Xcode, make the following changes:

/* The number 5 */
"Five" = "Cinq";

/* The number 4 */
"Four" = "Quatre";

/* The number 1 */
"One" = "Un";

/* The number 3 */
"Three" = "Trois";

/* The number 2 */
"Two" = "Deux";

In real life (unless you're multilingual), you would ordinarily send this file out to a translation service to translate the values on the right of the equals signs. In this simple example, armed with knowledge that came from years of watching Sesame Street, we can do the translation ourselves.

Now save, compile, and run—our application is now fully localized for the French language. We've provided you with the information in the Resources subfolder of 17 LocalizeMe to do the German and Canadian French localizations if you want some more practice. You'll find two more copies of the icon.png, flag.png, and Localizable.strings file if you want to try adding support for additional languages.