Few applications exist that don’t display text either in the interface (dialogs, buttons, window title bars, and so forth) or in a window (text from a file). If you plan to distribute your application in more than one language, you’ll need a strategy for internationalizing it, that is, localizing the application as appropriate for a particular language or region of the world.
Resources simplify the process of internationalizing an application. An application bundle (explained in Chapter 3) can contain multiple sets of resources, grouped by language and locale. By combining all these resources in one package, you can create one version of your application that is localized for multiple languages. Translations of the application’s text strings are among the resources stored with the executable in the application’s bundle.
Project Builder supports localization by organizing resources into language-specific, or .lproj folders.
We won’t cover all localization issues in this chapter. Instead, we’ll focus on how to use language-specific folders to store strings.
To that end, you’ll:
Review language-specific (
.lproj) foldersProvide an overview of what you can put in them
Look at a localizable strings file and how to retrieve a string from it
Create a window and a localizable strings file that contains text to display in the window
When you create a project in Project Builder, it checks to see under which development region you’re running the operating system. Then it creates the appropriate .lproj folder in which you can place all resources that are localized, or at least appropriate for localization. For an English development region, a project has an English.lproj folder.
For a Spanish development region, a project has a Spanish.lproj folder, and so forth.
To localize an English application for French, you must create a French.lproj folder. Then you put all the resources localized for French into that folder.
You create other folders for each language or locale you plan to localize.
At the very least, a language-specific folder should contain:
An
InfoPlist.stringsfile for localized versions of information properties associated with the application that a user will see, such as name and versionA Help folder that contains help files for your application
One or more nib files for the resources created using Interface Builder
A
Localizable.stringsfile for the text strings used in the application
Figure 8.1 shows a set of language-specific folders for the Moon Travel Planner application. The folders have a parallel structure. Note the names of the items in each folder are not localized, but the resources in the each item have been translated appropriately. In the next sections, you’ll take a look at what’s in each resource.
An information property list is a file containing key-value pairs that describe properties of the application, such as the version and copyright information. Some properties, such as the application signature, are never seen by the user. Other properties, such as the application name and version, are displayed in the interface in such places as an About window or the Finder’s Info window.
In Chapter 10 you’ll learn how to modify information properties from within Project Builder.
However, all that does is to create a property list for the language of the primary development region, stored in a file called Info.plist.
You must put the properties the user will see into an InfoPlist.strings file, create localized versions of that file, and store each localized InfoPlist.strings file in the appropriate language-specific directory (a typical InfoPlist.strings file is shown in Figure 8.2). This convention assures that your application gets the appropriate string for the language environment in which the application launches.
The help folder contains HTML files that display in the Apple Help Viewer. You need to make sure the files conform to the guidelines for Apple Help. You can find the guidelines along with a tutorial for creating a help folder in the Apple Help Software Development Kit (SDK), available from the Apple Developer web site. Information on adding a help folder to an application and registering a helpbook with the Help Center is covered in Chapter 12.
You need to localize help content and any special index terms and keywords you include in the files. As long as you place the appropriate localized help folder in each language-specific directory, your application should launch the version of help that matches the language or locale of the user’s operating system.
Any nib-based Carbon application will have at least one nib file that contains the resources for the main menu and a main window. Any interface object that displays text needs to be localized. Menus, window titles, and labels for controls are some of the items that usually contain text.
When you create a nib-based Carbon project, Project Builder automatically puts a nib file called main.nib in the language-specific folder (such as English.lproj)
for the development region of the operating system. You need to put localized versions of your project’s nib files into the appropriate language-specific folders.
There are many cases when an application needs to display text, such as for a login screen. It makes sense to store these strings so they can be localized, rather than hard-coding them in the application.
Strings that need to be localized should be defined in a separate file named Localizable.strings.
After you’ve translated the strings, you’d put the localized version of the file into the appropriate language-specific folder.
You can put any number of strings in a Localizable.strings file.
To distinguish one string from another, you need a key. You’ll use the key to retrieve the text when you need to display it in your application. Figure 8.3 shows a sample file that contains one string with the key “LoginScreen.”
You create a Localizable.strings file in Project Builder by choosing New File from the File menu. Create an empty file named Localizable.strings and then add it to the Resources group in your project.
The contents of the file must follow this syntax:
Do not translate the text keys, just the strings. You use the key to retrieve the string; the user doesn’t see the key.
You use the Core Foundation Bundle Services function CFCopyLocalizedString to get the string associated with the key. This function takes two parameters:
CFCopyLocalizedString returns the text associated with the key as a CFStringRef data type.
Note
A CFStringRef is a reference to a CFString
object. CFString objects are opaque data structures used by Mac OS X to efficiently store string data.
Example 8.1 shows you’d retrieve the text shown in Figure 8.3. The function CFSTR converts a string (such as “LoginScreen”) to a CFStringRef data type.