Learning iOS Development: A Hands-on Guide to the Fundamentals of iOS Programming (2014)

Chapter 5. Localization

At this writing, the Apple App Store is available in 155 countries. In most of those countries, English is not the native language. Even if there are people who speak English in a country, it is still best to show your app in a customer’s native language. That person can always choose to show it in English. And even English is not just English. There’s British English, American English, Australian English, Canadian English...and they all have differences.

iOS provides ways to localize entire screens, some or all of your strings, or even just an individual image. Thanks to auto layout, most apps can focus on strings and perhaps on updating some layout constraints.

In this chapter, you add two more languages to the CarValet app and look for places where constraints might need to change. You start by exploring localization and prepare your app and scenes for localization. As part of this, you find strings that could cause problems.

German is the first language you add. As you localize, you update some interface elements and constraints. Then you reverse your perspective on writing by adding Arabic, including delving into locales by localizing numbers and dates. While doing that, you find out that there are really four ways to set the locale of a device.

When you are done, you will be able to create apps that are ready for localization from the start, which is much easier than retrofitting existing apps.

Localization Basics

When you want an app to support many languages, you need to write only one app. iOS makes it easy to dynamically update your interface based on the user’s language preferences.

To find those preferences, in the simulator or on a device, open the Settings app, tap General, and then tap International. You should see a screen like the first one in Figure 5-1. Tap Language and then scroll through the list. When you choose an item from the list, the system updates the interface with the new language. The same choice enables apps to update. The third screen, which appears after you tap Region Format on the International screen, allows you to change how numbers and dates are presented.

Figure 5-1 International settings

You localize an app by using two basic iOS mechanisms: redirection and formats. Each mechanism is used to present different types of localized content. Redirection is for user interface (UI) elements, resources, and strings. Formats are for showing and reading numbers and dates. Occasionally, there is also code to write outside of these mechanisms as you see when localizing for Arabic.

Redirection

Whenever you load a resource, the system uses an indirection step to check for a local version. Resources can include storyboards, XIB (IB interface definition) files, sounds, images, and tables of strings. If a localized version is found, the system uses it; if not, the system uses a default value. You add new languages by adding files and data for that language.

A project starts with English localization. Figure 5-2 shows the project view from the Chapter 5 starting version of CarValet. In the Info panel is a category called Localizations with two items. One is a language—in this case, English.

Figure 5-2 Project-level localization

For CarValet, there is also a “language” called Base. This is considered the default localization. If the device is running in Swahili, and the system cannot find the localized version of a string, picture, or other item, it uses whatever is in Base. That happens because the checkbox to use a base localization is checked. If it were not checked, the system would still use redirection by looking at the top level of the app bundle. (App bundles and how they are organized is beyond the scope of this book because Xcode manages them in all but the most complex cases, and using Base localization is strongly recommended.)

The localizations area also has buttons to add (+) and delete (–) localizations. As you can see, both English and Base already have two localized files. So far you have done no work to localize, so what and where are these files?

To find those files, look in your project folder in the Finder for a folder called Base.lproj. The two files inside that folder are both storyboard files, one for iPhone and one for iPad. So far, you have only edited the iPhone version.

When you add another language, another folder is created. Any content specific to the new language goes inside the new language folder. Every folder has a similar name, <LanguageCode>.lproj:

<LanguageCode> is the internationally recognized two-letter code for the language.

lproj means “language-specific project directory.”

When you add German later in this chapter, a folder called de.lproj is added. de is the internationally agreed-on, two-letter code for German, or “Deutsch.” You can find some of the two-letter codes in the iOS documentation. The letters are part of the larger ISO 639.2 standard, available at www.loc.gov/standards/iso639-2/php/code_list.php.

Any time the system needs to load a resource, the first place it looks is the language-specific project directory folder (lproj) for the current device language. If the system doesn’t find anything, it looks in the base localization. This redirection step makes localization much easier for you.

String Tables

If you want to present an entirely different set of scenes on the iPad after adding Chinese to your product, add an iPad storyboard file with the same name to the Chinese folder, zh.lproj. In your project, the iPad storyboard is called Main_iPad.storyboard. A Chinese-specific storyboard would have the same file name and be in the Chinese folder. On an iPad set to China, iOS looks in that folder first and finds the specific Chinese storyboard. For any other language, it checks in the language folder and does not find a storyboard file, so it uses the default, or English, storyboard.

For most apps, different screens are rarely needed. Usually most of the work is localizing the strings displayed to the customer. Again, this is done by redirection, using a different type of file, called a string table.

Each string table consists of pairs of lines in a string table, which are at the heart of string localization. Each pair looks like this:

/* Documentation about SomeStringKey */
"SomeStringKey" = "ALocalizedSomeString";

The first line in each pair is documentation to help translators figure out what the localized string should be. The second line is like a dictionary with a key and a value. "SomeStringKey" is a key to identify the particular localized string. Some people use the native language equivalent of the string, such as “Previous” or “Edit.” The recommended key name, such as "PreviousButtonTitle" or "EditButtonTitle", helps identify what the string is for.

"ALocalizedSomeString" is the localized version of the string. Unlike with localized storyboard files that the system finds, you write the code to get a localized string using NSLocalizedString. The two arguments correspond to the line pairs in a string table file:

NSLocalizedString(SomeStringKey, SomeStringDocumentation);

SomeStringKey is the key side shown on the second line of the preceding code example.

SomeStringDocumentation is the documentation string shown on the first comment line.

When you ask for a string this way, the system goes through a few steps:

1. It looks for a file called Localizable.strings in the lproj folder for the current device language.

2. If it finds the file, it looks for SomeStringKey, and if it finds it, the system returns the associated string.

3. If the system does not find either the file or string key, the system looks for the key in the Localizable.strings file in the Base localization folder and returns the associated string.

You might wonder why there needs to be documentation for every localized string. Languages can have many features and may require different words and/or modifiers, depending on the use of a particular concept. Languages can have any, some, or all of the following features:

Gender specificity—Nouns can be feminine, masculine, or neutral, and modifiers (verbs, adverbs, and so on) have to match gender.

Number matching—Different words, conjugations, or other elements are required if the noun is singular or plural.

Tense matching—Different words, conjugations, or other elements are required if the noun is past, present, and/or future tense. In addition, languages may have only two tenses or even no tense.

Modifications for statement versus question—Different words, conjugations, or other elements are required if the sentence is a question rather than a statement.

Modifications for yes or no—Different words, conjugations, or other elements are required if an answer is a yes or a no.

For example, German has both gender and number matching. The word car is gender neutral, so a car is das auto, while more than one are die autos. If you are talking about a make, those are usually masculine, such as der Porsche, with multiple makes still using die. Japanese includes statement versus question, yes versus no, and tense modifications. Arigato gozaimasu is “Thank you for what are you are doing”; Gozaimashita makes it “for what you have done”; Wakarimasuka is “Do you understand?”; Wakarimasu is “I understand”; and Wakarimashita is “I do not understand.”

You call NSLocalizedString (or, as you see later in this chapter, one of its variants) any time you need to display something to the user. This includes setting the text of buttons, labels, and other static elements. It does add some extra code to initializing views, but the one line works for displaying strings from any of your app’s localized languages.

The final part is creating the string tables. Apple provides a way to build the table from the command line by using genstrings, which looks for calls to NSLocalizedString or variants. The string table is built using the key and documentation arguments. Adding a new localization makes a copy of the existing default string table.

Formats

When you localize an app, you are really localizing four things:

The language displayed in your interface—In the United States, the title for a button to show the next car is Next; in German, it is Nächstes.

The order in which you display text items and some controls—This comes up in two main ways: sort orders and order of words or visual elements. The last part comes from languages that are read right-to-left. You learn more about this later in the chapter.

Specific graphical elements or even whole scenes that may need to change—All but whole scenes is made much easier using the language project folder mechanism discussed earlier.

Changing whole scenes is very rare and is usually due to one of two things: String length and/or localized iconography make it impossible to adjust the layout using constraints or due to cultural differences.

The formats for dates, numbers, and other items—In the United States, dates are month/day/year; in Canada or the UK, it is day/month/year. German reverses the use of the comma and period in decimal numbers: 1.000,1 is one-thousand point 1. The system provides classes and convenience methods for converting numbers and dates to and from localized strings.

Only some of these things are controlled by the selected language. In addition to setting a language for a device, a user can set a regional format or locale. This is done through the right-hand screen in Figure 5-1.

The locale is set independently of the language. It is perfectly fine for a user to set the language to (U.S.) English and locale to the United Kingdom or even to German. A locale specifies conventions for displaying numbers, date and time formats, and other things.

Most apps show generated numbers and dates as part of their interface. Apps may also parse entered number or date strings. Unlike static strings, you cannot translate numbers and dates in advance. In the physical world, how to display or read information varies from country to country and even from region to region in a country. On iOS, it varies by locale.

There are many rules for how to display numbers, ranging from where separators go and what character to use for the separator and decimal points, to the characters used for the numbers themselves. Dates are far more complex and can vary in the order of elements displayed, separators used, and even the number of months.

An example of order of display is showing the day, month, and year. In the United States, the standard is to display “month, day, year” or “mm/dd/yyyy.” In Canada, just next door, the order of days and months is reversed, though the separators are the same—that is, “day, month, year” or “dd/mm/yyyy.” In China, it is “year, month, and day” with a special character after each element, then a space, and no other separator.

Calendars also differ. Most of the West uses the Gregorian calendar. Japan uses the Imperial calendar, based on the reign of the current emperor. The Gregorian year 2013 represents a year almost 2,000 years in the future in the Imperial calendar. On the Hebrew calendar, 2013 is more than 3,000 years in the past. The English language setting offers a choice of three calendars: Gregorian (the one you are probably used to), Japanese, or Buddhist.

iOS providers two key classes that let you simplify displaying the correct format and parsing input in your apps:

NSNumberFormatter is used to display and read numbers formatted for a locale.

NSDateFormatter is used to display and read dates and times formatted for a locale.

Other classes are used for calculating dates and time units:

NSDate represents a date in the current calendaring system. It is really just a point in time wrapped in methods.

NSCalendar represents a calendaring system that includes information on the number of days in a week, months in a year, or days in a particular month.

NSDateComponents is used for initializing dates from pieces and for time and date math. You can read or write the individual components of a date by using the current calendar as well as add or subtract different units of time.

You should never do math assuming that there are 60 seconds in a minute, 60 minutes in an hour, and 24 hours in a day. Doing so is fraught with problems such as leap years and variations in daylight savings, not to mention different calendars.

NSTimeZone represents a time zone and is important in the correct display of dates and times.

You will look at formats in more detail as you internationalize your app. Notice the word internationalize in the last sentence. There are two processes involved in adding a new language to your app:

Localization is the process of preparing an application for other languages. This is when you set up the default language lproj folder, localize strings and generate string tables, and prepare for other types of content that can change as the language changes.

Internationalization is configuring the content and files for a specific country. It is adding a language’s lproj folder and setting up, for example, strings for German or the special graphics for Japan.

The next section guides you through localizing the CarValet app.

Preparing the App for Localization

To prepare the CarValet app for other languages, you need to know the following:

All the static strings that are displayed and where they are defined

All the dynamic strings that are displayed and where they are created

All places that display dates and where they are defined or created

All places that display numbers and where they are defined or created

All places that parse dates or numbers entered by the user and that are read from the interface

Any culturally specific graphics and where they are defined (for example, an upside-down triangle is used to represent a stop sign in Japan)

For CarValet, there are very few strings shown and only two places where numbers are read. Figure 5-3 shows both of the related screens. All the strings to localize are highlighted in green, display only numbers in red, and numbers that are both displayed and read in blue. The Done button is not highlighted as it is a system button so iOS does the localization for you.

Figure 5-3 Strings and numbers to localize

For other apps, you need to know some other information:

All places where lists of ordered strings are presented

All places attempting to autocomplete entered text

All places searching strings, especially for user display

All places requiring access to strings on a character-by-character basis, such as finding the position of a character or iterating through characters

The first item is because sort orders can vary widely between different countries and locales. Most of the rest are because a character might not be a character. The key to understanding this is, well, a key:

The key emoticon is not just one character. Although it may only take one “key” press from a special keyboard, it is really a number of elements that combine to make one user-visible character, or glyph. The same is true of many languages. Not just an obvious one such as Korean, but even French, where multiple key-presses combine to make an accented character.

Although most of this is beyond the scope of this book, the basic approach is to use methods for NSString that are locale-specific as well as checking text input for completed user-visible glyphs versus marked, or in-progress, glyphs.

For CarValet, the next step is to add code to read language-specific strings. The code you add is then used to generate the first string table. You can use the CH05 CarValet Starter project provided with the sample code or continue with your project from the previous chapter.

Setting Up Localization for the Add/View Car Scene

The existing InfoPlist.strings string table is for localizing items from CarValet-Info.plist, such as the application name. You need a different string table to localize the interface.

The first step is to add the calls to read localized strings. You call NSLocalizedString with a key to the string table and an argument documenting the meaning of the UI element. Make the following changes in ViewController.m:

1. In displayCurrentCarInfo, change the withBaseString: argument in the call to the updateLabel:withBaseString:andCount: method:

withBaseString:NSLocalizedString(
@"Car Number",
@"Label for the index number of the current car")

2. Similarly, change the withBaseString: argument in the newCar: method:

withBaseString:NSLocalizedString(
@"Total Cars",
@"Label for the total number of cars")

The calls to NSLocalizedString contain enough information to create a string table. Instead of manually creating one, you use genstrings to generate the table from your .m file(s):

1. Open the Terminal application on your Mac.

2. Navigate to your code directory. The easiest way to do this is to type cd and a space at the command line in the Terminal window and then drag the CarValet folder from the Finder (the one at the same level as the CarValet.xcodeproj file) into the Terminal window. A long path name appears. Press Return in the Terminal window, and you are in the project folder. You can easily confirm this by typing ls and pressing Return to list the contents of the directory. You should see all the .m, .h, and other files, as well as the en.lproj folder.

3. Use genstrings to generate the English strings localization file. In the Terminal window, type the following command and then press Return:

genstrings -o Base.lproj *.m

-o indicates the output folder, and *.m tells genstrings to look in each .m file for possible localized strings—that is, code that uses any of the NSLocalizedString macros.

After you complete these steps, the Base.lproj folder has a new file called Localizable.strings that contains the UI string table. Notice that you are setting up the base localization, the default for any localization item not defined in a specific language. Add that file to your project, in the Supporting Files group. Take a quick look at the project localization screen you saw in Figure 5-2. The base localization now has three files instead of two.