Guidelines for Internationalization

The following sections provide recommendations on how to internationalize your software to take advantage of the support available on your target platform.

Use Canonical Language and Locale IDs

OS X v10.3 added support for obtaining canonical locale IDs through Core Foundation functions associated with the CFLocaleRef type. In OS X v10.4 and later (and iOS), support was added for getting canonical language IDs. In OS X v10.4, the NSLocale class was added, bringing similar support to the Foundation framework. (These features are also available in iOS.) If you get the user's preferred locale ID through the NSBundle class or Core Foundation bundle functions, then you should already be receiving a canonical locale ID.

For information about language and locale IDs, see “Language and Locale Designations.” For information on how to get canonical language and locale IDs, see “Getting Canonical Language and Locale IDs in OS X.”

Use Bundles

The bundle mechanism simplifies the process of localization by letting you place localized resources in separate directories named for the language or region they support. Both the NSBundle class and CFBundleRef functions use this collection of resource folders to localize a program based on the current user’s language and region settings. This mechanism makes it possible for a bundled program to display itself in different languages for different users. Organizing resources by directory also makes it easy to add new localizations later.

Support Unicode Text

Applications should use Unicode-based technologies in all situations that involve displaying text to the user. Unicode support is essential for multibyte languages and the system supports some languages (including Arabic, Thai, Greek, and Hawaiian) only through Unicode. Regardless of whether you localize your software for multibyte languages, you should still support Unicode so that users can enter text data in their native language.

The system provides extensive support for managing and displaying Unicode text. Core Foundation and Cocoa strings provide a way to store Unicode strings in your application. In OS X, technologies such as Core Text, Quartz, and Cocoa Text all leverage Unicode in the display of text. Use of these technologies makes it possible to support virtually any language.

While Unicode is important for text that is displayed to the user, you do not need to use it everywhere in your application. For example, you might not need to use Unicode for debugging text or internal logging mechanisms, unless you want those messages to be translated and displayed to users.

Guidelines for Adding MultiScript Support

An application that provides multiscript support can accurately display text in various scripts simultaneously. Such an application can accept text input, display text, and print text containing the scripts of different languages in the same document, regardless of a user’s language preferences. If an application were not prepared to offer multiscript support, some of this text would not appear correctly.

Multiscript support is becoming an increasingly important and expected feature not only for operating systems but for third-party applications. Users expect to be able to create a document in one language, change their language preference, and then open the document as they last saved it.

To add multiscript support to an application, you must use the appropriate Unicode technologies and API. The classes of the Foundation framework automatically provide multiscript support.

For more information on file encodings in OS X, see “File Encodings and Fonts.”

Carefully Consider Translatable Strings

When writing text for your application, try to think about how that text might be translated. Grammatical differences between languages can make some text difficult to translate, even with the formatting options available in strings files. In particular, strings that require differentiation between singular and plural forms (because of a count variable, for example) may require different strings in different circumstances. Talk to your translation team about ways to eliminate potential translation problems before they occur.

For more information about creating strings files, see “String Resources” in Resource Programming Guide.