< Previous PageNext Page >

Hide TOC

Support for Internationalization

Mac OS X supports internationalization and localized content in a variety of ways.

It allows the user to specify a set of preferred languages.
It provides a mechanism for storing multiple language-versions of resources within an application.
It offers APIs and tools for generating string tables and for accessing localized strings.
It allows additional languages to be easily added to an application, even at run time.
Through Xcode, it provides project support for internationalization.

The notion of a preferred language set and the mechanisms of bundles, localized resources, and runtime binding are behind this support.

Language Preferences

The Language pane of the International system preferences (Figure 1) lets users set language based preferences for their computing environment. The preferences system (described in Runtime Configuration Guidelines) stores an ordered list of languages as a per-user default under the key AppleLanguages. Thus a user who understands more than one language can specify alternatives if an application does not include a localization for his primary language.

Figure 1 Language pane of the System Preferences International module

When a bundle requests a resource, the bundle interfaces try to choose a resource whose localization most closely matches the language and region settings in the user preferences. If a localization does not exist for the user’s preferred language, the search continues for the user’s second preferred language, and third preferred language, and so on. If none of the bundle’s localizations match the user preferences, the interfaces return the localization used during development of the bundle.

Note: For more information on how you store language-specific resources in a bundle, see Bundle Programming Guide in Core Foundation Documentation. For information on how to identify your bundle localizations to the CFBundle functions or NSBundle class, see “Specifying Supported Localizations in Your Bundle.”

Core Foundation Bundle Services (CFBundle) helps C-based applications retrieve the localized resources they need. The Cocoa NSBundle class provides the same capability for Objective-C and Java-based applications. In general, your application does not need to know which language is preferred by the user. The CFBundle and NSBundle interfaces automatically return the resource file that is most appropriate for the current user.

Locale Preferences

Locale preferences convey regional differences for the way dates, times, and numbers are displayed. Mac OS X includes predefined locales for many world regions. However, the user can also customize the information in these default locales to further personalize the system. Figure 2 shows the Formats pane of the International system preferences, where users can customize their locale settings.

Figure 2 Locale information in Formats pane

In most cases, your code should never have to worry about applying locale preferences. Most APIs take the user’s preferences into account when getting or formatting locale-sensitive data. However, there may still be situations where you need to get locale information. For example, you might want to display the current locale settings, do comparisons of different locales, or apply locales other than the current locale to a specific piece of data. In those situations, the Core Foundation provides the CFLocale opaque type for getting locale information. For more information on locales and how to get locale-related data, see Locales Programming Guide in Core Foundation Internationalization Documentation.

Bundles

An application bundle, also known as a file package or application wrapper, is a directory containing an executable file and its associated resources. Application bundles are opaque directories, so to the user they look like files. Double-clicking an application bundle causes the application to be launched by the system.

Mac OS X supports other types of bundles, such as plug-ins and frameworks, too. A plug-in bundle contains code and resources like an application bundle but cannot be launched directly by the user. A framework bundle contains a dynamic shared library and resources to support that library. Unlike many other types of bundles, a framework is not stored in an opaque directory. The framework bundle directory is open so that developers can examine any header files and resources included with the framework.

Inside an application, the term “bundle” is often used to represent an instance of the NSBundle class or the CFBundleRef type. You use these objects to acquire resources from a bundle directory. Both objects automatically take the user's language preferences into account when looking for resources.

For more information about how bundles locate resources, see Bundle Programming Guide.

The Structure of a Mac OS X Application Bundle

An application bundle has a structure similar to the following:

Listing 1 Application Bundle Structure

MyApp.app/                          application wrapper

    Contents/

        MacOS/

            MyApp                   application executable

        Info.plist

        Resources/                  all resources go here

            MyApp.icns

            PeaceSign.tiff          non-localized resource

            en.lproj/               resources localized for English

                StopSign.eps        localized image

                Localizable.strings dynamically displayed text

                MyApp.nib           default platform nib

                MyApp Help/         help files

            fr.lproj/               resources localized for French

                StopSign.eps

                Localizable.strings

                MyApp.nib

                MyApp Help/         help files

            ja.lproj/               resources localized for Japanese

...

As you can see from this structure, your internationalized application needs one .lproj directory for each supported localization. The directories are named according to the language-version of the resources they contain. You do not have to create or populate these folders manually; Xcode does much of that work for you.

Each .lproj directory initially contains a copy of your application’s native-language resource files. The resource file names must be identical in each of the .lproj directories. When you are ready to localize, you give the resource files to the translators to work on. They then translate the contents of the files and return them to you for inclusion in your Xcode project.

If your application displays resource file names to the user (such as image file or sound file names), you should store the resource file names themselves in a .stringsfile. This way, you can translate the name of the resource file as well as its contents. To load the resource, you first request the resource file name from the corresponding .strings file. Once you have the name, you can load the resource as usual.

Files within the .lproj directories can be of the following types:

Nib files These files, created by the Interface Builder application, are encoded archives of user interface objects, custom-object references, and inter-object connections. The encoded user interface objects can include statically-displayed strings, images, and sounds.
Nib files are typically localized directly, using Interface Builder. A localizer takes a nib file (or, more typically, your application’s set of nib files), translates all the user interface strings, and makes other adjustments as necessary, such as resizing user interface objects and replacing culture-specific images and sounds.
It's a good idea to design your application so that each window or panel is stored in its own nib file. This improves the performance of your application and also permits localization to progress incrementally.
Images Cocoa applications can use EPS, TIFF, PICT, GIF, JPEG, BMP, and ICO files, as well as other supported image-file formats. You can also include QuickTime movies.
Localized text strings A .strings file (Localizable.strings by default) contains dynamically-displayed strings for a given locale. For more information, see “Strings Files.”
Sounds
Online help Online help files are in HTML. The application’s property list allows you to specify which file your application should open when the user chooses the Help command. A localized variant of your help should be placed in the appropriate .lproj directory for each targeted localization.

For localization, you’ll send the source-language .lproj folder (en.lproj for developers in English-speaking countries) to a localization service, or to your in-house translation department. You’ll also need to send the compiled application to allow your localizer to view dynamically-loaded resources in context, to ensure appropriate translations, and to ensure adequate dimensions for user interface elements that display dynamically-loaded resources. For each target language, they’ll send back a .lproj folder in which each resource file has been appropriately localized.

The tool used to edit resources varies by resource type. You can edit .strings files with any text editor. If possible, use an editor that can save text in Unicode format, such as the TextEdit application included with Mac OS X. String files saved in Unicode format can be used in a running application directly, while other file formats require conversion first. Localizers edit nib files using Interface Builder and edit other resources (images, help files, sounds, and so on) with a tool appropriate to the file format and to your needs.