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.”
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.
Wherever possible, use the
NSStringobjects instead of C strings.
NSStringobjects store and handle Unicode data internally without requiring you to have any specific knowledge of the global character-set standard. If you need to convert between Unicode and C strings in other encodings, use the facilities that Foundation provides. However, avoid converting
NSStringobjects to and from C strings or if possible. Such conversions are computationally expensive and frequently introduce bugs affecting multiscript presentation. If you cannot find any or Unicode-aware interfaces to use in a certain situation, convert the string to the application’s text encoding.
Use formatter objects to interpret dates and numbers and to present them to the user.
For localized strings, use the
NSLocalizedStringmacro (and related macros) .
You can not assume that all text data uses the MacRoman encoding or ignore text encoding issues altogether. Untagged text data unaccompanied by script code is not necessarily in the system script (Roman). If you make this assumption, users may be presented with incoherent text. In the worst case, your text processing routines could misinterpret the text and either corrupt user data or crash the system.
In OS X, avoid accessing system layers below the Core Services framework.
You should be able to obtain most of the functionality available in the kernel environment (particularly BSD and Mach calls) using the Core Services frameworks. As much as possible, avoid calling BSD functions directly. For accessing the file system, use
NSURLobjects or the
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.
© 2003, 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-01-09)