< Previous PageNext Page > Hide TOC

Localizing Pathnames

In order to provide a better user experience, Mac OS X supports the ability to display localized names for system and application directories. Localized pathnames make it easier for international users to find information, but do so in a way that does not impede your application. The implementation of this feature merely replaces the name of some directories with a localized version when they are displayed to the user. The actual path information on the hard disk does not change.

There are two ways to support localized pathnames. The first is to display them in your application. The second is to localize the names of any directories associated with your application.

The following sections explain the process for getting localized pathnames and for localizing your application’s path information. For more information on localizing your application menus and content, see “Preparing Your Nib Files for Localization.”

Contents:

Getting Localized Path Names
Localizing Your Application Name
Localizing Directory Names

Getting Localized Path Names

You need to be aware of localized path names in your application and display them appropriately. Localized path names are for display only and should never be used to access the file system. For the most part, you should continue to use the actual pathname when working with files and directories in your code, including when you need to write to caches or user preferences. The only time you should use a localized path name is when you want to display that path to the user through your application’s user interface.

Mac OS X provides several functions for obtaining the localized name of a path. You should always use one of these functions to convert a path to its localized name immediately prior to display. All applications can use the Launch Services methods LSCopyDisplayNameForRef and LSCopyDisplayNameForURL to retrieve localized display names. Cocoa applications can also use the NSFileManager methods displayNameAtPath: and componentsToDisplayForPath: to retrieve this information.

Localizing Your Application Name

If you have a bundled application, you can specify a localized display name for your application. The Finder displays localized bundle names based on the current language settings. Other applications can request your application’s localized name as well and display it as appropriate.

You specify localized names for your application using the existing bundle localization mechanism. The Resources folder of your application bundle contains one or more language-specific resource directories. (See “Anatomy of a Modern Bundle” in Bundle Programming Guide for information about bundle resource directories.) In each of these language-specific directories, you can include an InfoPlist.strings file with a list of localized property-list keys. One of the keys you can include in this file is the CFBundleDisplayName key, whose value you can set to the localized name of your bundle.

At all times, Mac OS X prefers user-customized display names over the default and localized names you specify in your bundle. If the on-disk application name is different than the non-localized version of your bundle display name—that is, the name associated with the CFBundleDisplayName key in your Info.plist file—the system assumes the user made the change and returns the customized name. If at some later time, the user changes the application name back to the original name, the system reverts to using the localized values from your application bundle.

Localizing Directory Names

If your application package installs any custom support directories, you can provide localized names for those directories; however, doing so is not required. If you want to localize your application’s support directories, you should do so only for directories whose names are known in advance by your application.

To localize a directory name, add the extension .localized to the directory name. Inside your directory, use the Terminal application to create a subdirectory called .localized. Inside this subdirectory, put one or more strings files corresponding to the localizations you support. Each strings file is a Unicode text file. The name of the file is the appropriate two-letter language code followed by the .strings extension. For example, a localized Release Notes directory with English, Japanese, and German localizations would have the following directory structure:

Release Notes.localized/

    .localized/

        en.strings

        de.strings

        ja.strings

Inside each of strings files, include a single string entry to map the non-localized directory name to the localized name. For example, to map the name “Release Notes” to a localized directory name, each strings file would have an entry similar to the following:

"Release Notes" = "Localized name";

For information on creating a strings file, see “Creating Strings Resource Files.”

< Previous PageNext Page > Hide TOC