< Previous PageNext Page > Hide TOC

Working With Localized Strings

Bundles are able to retrieve localized strings to best suit the user’s preferences. Whereas they return a path for other resources, bundles know how to lookup and return strings from within strings resource files.

Both CFBundle and NSBundle define a single interface for retrieving strings. For CFBundle, it is the CFBundleCopyLocalizedString function. For NSBundle, it is the localizedStringForKey:value:table: method. However, both Cocoa and Core Foundation also define convenience macros for retrieving strings from known locations.

There are several advantages to using the convenience macros instead of the corresponding CFBundle and NSBundle API. First, the macros are easier to use for certain common cases. Second, they are recognized by genstrings command-line tool, which automatically creates strings files based on the contents of your source code. (The CFBundle and NSBundle API are not recognized by genstrings.) Third, the macros let you specify a comment string argument to aid the translator. Comments are ignored by the compiler, but genstrings uses the information to annotate the generated strings files.

Core Foundation defines the following convenience macros:

• CFCopyLocalizedString

• CFCopyLocalizedStringFromTable

• CFCopyLocalizedStringFromTableInBundle

• CFCopyLocalizedStringWithDefaultValue

The Foundation framework in Cocoa defines the following convenience macros:

• NSLocalizedString

• NSLocalizedStringFromTable

• NSLocalizedStringFromTableInBundle

• NSLocalizedStringWithDefaultValue

Listing 1 demonstrates the proper usage of the Core Foundation convenience macros. The first argument of each macro is both the text to translate and the key to use when looking up the string. This string appears in the native language of the author of the program. Subsequent macros let you specify the specific strings file to search and the specific bundle to search. The final macro also lets you specify a default translation for the string if no other version is found. (Note, that the corresponding Cocoa macros use essentially the same syntax but with different data types.)

Listing 1  Using the LocalizedString macros

    CFStringRef localString;

    localString = CFCopyLocalizedString(

        CFSTR("String text to translate"),

        CFSTR("Comment to help translators."));

    localString = CFCopyLocalizedStringFromTable(

        CFSTR("String text to translate"),

        CFSTR("MyStrings"), // strings file to search

        CFSTR("Comment to help translators."));

    localString = CFCopyLocalizedStringFromTableInBundle(

        CFSTR("String text to translate"),

        CFSTR("MyStrings"), // strings file to search

        myBundle, // bundle to search

        CFSTR("Comment to help translators."));

    localString = CFCopyLocalizedStringWithDefaultValue(

        CFSTR("String text to translate"),

        CFSTR("MyStrings"), // strings file to search

        myBundle, // bundle to search

        CFSTR("Default translation if string not found"),

        CFSTR("Comment to help translators."));

When you run the genstrings tool on source code using the above macros, it creates one or more string files for the referenced keys. (See the man page for genstrings for instructions on running this tool.) For instance, suppose your code contains the following usage of the macro:

localString = CFCopyLocalizedStringFromTable(

            CFSTR("Yes"),

            CFSTR("MyStrings"),

            CFSTR("Label for an affirmative answer") );

After running genstrings, you would have a file called MyStrings.strings. with the following data in it:

"Yes" = "Yes"; /* Label for an affirmative answer */

You would then copy this strings file into each of your localized resource directories and translate each entry to the appropriate language. For example, translating the preceding listing from MyStrings.strings placed into French would yield the following entry:

"Yes" = "Oui"; /* Label for an affirmative answer */

For additional information on working with strings files, see “Extracting Localizable Strings From Your Code” and “Loading Localized Strings” in Internationalization Programming Topics.

< Previous PageNext Page > Hide TOC