What Is Internationalization?

For the purposes of this discussion, we distinquish between the terms localization and internationalization as follows:

Localization is the process of changing an existing software product to make it suitable for use in a new language or locale. This process includes changing all user-visible text to a different language, replacing inappropriate images and sounds with locally-acceptable alternatives, and changing various formats and units of measurement to those used in a given locale. If the users of a given locale feel comfortable using an application because it meets their expectations regarding language, culture, and data formatting, you can say that the application has been successfully localized for that locale.

Internationalization (the subject of this page) is the process of designing and implementing a new software product so that it is easy to localize. This means taking advantage of operating-system features that facilitate localization instead of hard-coding the product to one locale.

Resources

Mac OS X resources, like their Windows counterparts, contain data needed by a software product--for example, text, icons, images, property lists, and data files. Unlike Win32 applications, which store resources in one or more dynamic link libraries (DLLs), Mac OS X stores some resources individually (for example, sound and image files), while other resources are stored in container files (for example, all of the application's text strings for a given language).

As you will see in the next subsection, resource files must be stored in specific locations. In addition, Mac OS X places restrictions on certain resources, including the specification of what resources must go into a given file and the name and location of that file.

Bundles

Porting to Mac OS X from Windows Win32 API stated that a bundle is a directory in the file system that contains executable code and related resources. Mac OS X supports several varieties of bundles. The type of bundle of interest here is called an application bundle, which is a directory that contains all the executable code and resources needed to implement an application. To simplify matters for the user, the Finder treats an application bundle like an executable file, not a folder--when a user double-clicks it, the Finder runs the application (as opposed to opening the folder).

One key fact to keep in mind is that Apple's development tool suite assumes that your application bundle is structured according to certain guidelines. Following these guidelines simplifies your code and automatically makes your application internationalized--that is, it ensures that your application can easily be localized to additional languages and locales.

The following figure shows the directory structure of a typical application bundle.

MyApp/

 MyApp /* alias to Contents/MacOS/MyApp */

 Contents/

 . MacOS/

 . . MyApp

 . . Helper Tool

 . Info.plist

 . PkgInfo

 . Resources/

 . . MyApp.icns

 . . Hand.tiff

 . . Horse.jpg

 . . WaterSounds/

 . . en_US.lproj/

 . . . MyApp.nib

 . . . bird.tiff

 . . . Bye.txt

 . . . house.jpg

 . . . house-macos.jpg

 . . . house-macosclassic.jpg

 . . . InfoPlist.strings

 . . . Localizable.strings

 . . . CitySounds/

 . . en_GB.lproj

 . . . MyApp.nib

 . . . bird.tiff

 . . . Bye.txt

 . . . house.jpg

 . . . house-macos.jpg

 . . . house-macosclassic.jpg

 . . . InfoPlist.strings

 . . . Localizable.strings

 . . . CitySounds/

 . . Japanese.lproj/

 . . . MyApp.nib

 . . . bird.tiff

 . . . Bye.txt

 . . . house.jpg

 . . . house-macos.jpg

 . . . house-macosclassic.jpg

 . . . InfoPlist.strings

 . . . Localizable.strings

 . . . CitySounds/

 . Frameworks/

 . PlugIns/

 . SharedFrameworks/

 . SharedSupport/

The actual executable file is stored at Contents/MacOS/MyApp, while all the resources are stored in the directory Content/Resources.

In a bundled application, all the resources associated with a given language or locale are stored in a single directory, named <language name or country or language abbreviation>.lproj, within the Resources directory. For example, the directory for Japanese resources is named Japanese.lproj (Japanese is a language name), while the directory for the British version of resources for the English language is named en_GB.lproj (en_GB is a locale abbreviation, as specified by the ISO 3166 standard). A third way of specifying a localization directory involves indicating a language by its two-letter abbreviation, as specified by the ISO 639 standard; an example of this would be en for English.

As expected, each file in a .lproj directory has a counterpart with the same name in every other .lproj directory. Each such file has its content specialized for a different language or locale, but it must have the same name as its counterparts.

The User and Developer Perspectives

Before you can understand how to add international support to your application, you must first understand how Mac OS X presents the issue of international support to both the user and the developer.

The User's View

Users express their language and locale preferences through the International module of the System Preferences application. In the Languages panel of this module (see below), users can drag and drop names in the Languages scrolling list to indicate which language they prefer to work in (the language at the top of the list) and, if that language is not available, what other languages they prefer to use.

For example, with the settings shown above, the user has expressed her desire to see all software display text, numbers, and data according to the conventions assumed by people who identify with the Swiss dialect of French. If that is not possible, she prefers her software to display using French conventions. If that is not possible, she prefers English, Spanish, and so on down the list.

Mac OS X ensures that each application satisfies the user's language preferences to the best of the application's ability. One application, for example, may display its text and menus in Swiss French because it contains Swiss French resources. Another one (which lacks Swiss French, French, and Spanish resources but contains English resources) displays its text and menus in English because English is the closest that it can get to matching the user's preferences.

It is important to note this central assumption of Mac OS X users: All they have to do is set their language preferences in this one location. Once they have done this, whenever users open an application, Mac OS X will automatically use the resources within the application that best match their language preferences.

Unicode

Though the topic of Unicode was covered in Using Text in Mac OS X, one piece of information bears repeating here: Unicode is the basis of all text storage and manipulation in Mac OS X. Unicode makes it possible for Mac OS X to use the same system and application code to display such widely different scripts as Arabic, traditional Chinese, Italian, and Russian.

Internationalizing Static User-Interface Resources

Static user-interface resources are easy to find--they are the ones that you specify while building user-interface elements using Interface Builder. The output of Interface Builder is a file that ends with a suffix of .nib.

If a static user-interface element contains text or images that are locale-specific, the .nib file that contains them must be placed in the appropriate .lproj directory, and you must create a separate .nib file for each locale you are supporting. You will use Interface Builder to create each new version of the .nib while you are working on. For performance as well as for ease in localization, Apple recommends that you save all your menus in one .nib file and that you save each window or dialog in its own .nib file.

Languages vary by as much as 30 percent in terms of how much space a given phrase or sentence needs for it to be displayed on-screen. When you are localizing your user interface for additional languages, use Interface Builder if at all possible. By doing so, you can change an interface element's size and position as needed to accommodate any changes in text size.

Some resources, usually images and sounds, are the same for all locales but cannot be handled by using Interface Builder to insert them into your application. In such cases, you should store them directly in the Resources directory of your application bundle.

Internationalizing Dynamic User-Interface Resources

If user-visible text wasn't specified using Interface Builder, your code must somehow be displaying it dynamically. Mac OS X provides a way for you to write one set of code that will always retrieve the most appropriate localized string to your users. To do this, you must put all user-visible strings, formatted in a certain way, into a file with a name that ends with .strings. You must place this file within the appropriate .lproj directory, with one version of the file for each locale you are supporting. You can simplify your code slightly if you place these strings in a file named Localized.strings. A .strings file stores strings in key/value pairs, where the key is a string that is used to look up its associated value string, which is the actual string you want to display.

Most non-text resources have some meaning to the user (for example, the house.jpg image file in the application bundle shown earlier) and will be different for each culture. This means that they need to be placed inside the appropriate .lproj directory. This Guide recommends that, unless you absolutely know that a resource should be displayed the same way everywhere in the world, you place such non-text resources in .lproj directories.

Retrieving Localized Resources

To retrieve localized resources for use in your application, you will use functions from the CFBundle API. The structure of bundles is subject to change in the future. For this reason, it is important that you use functions from the CFBundle API for retrieving resources instead of hard-coding file pathnames into your application.

/* Message indicating file couldn't be opened; %@ is the filename. */

"Could not open file %@." = "Non posso aprire il documento %@.";

/* Message indicating file couldn't be opened; %@ is the filename. */

"Could not open file %@." = "Impossible d'ouvrir le fichier %@.";