---

Guidelines for Internationalization

The following sections provide recommendations on how to internationalize your software to best take advantage of Mac OS X.

Contents:

Use Canonical Language and Locale IDs
Use Bundles
Support Unicode Text
Guidelines for Adding MultiScript Support
Carefully Consider Translatable Strings

Use Canonical Language and Locale IDs

Mac OS X 10.3 added support for obtaining canonical locale IDs through the functions of CFLocale. In Mac OS X v10.4 and later, support was added for getting canonical language IDs. (Cocoa support was also added in Mac OS X v10.4.) If you get the user's preferred locale ID through the CFBundle functions or NSBundle class, 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.”

Use Bundles

The Mac OS X 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 CFBundle functions and NSBundle class 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 Mac OS X 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.

Mac OS X provides extensive support for managing and displaying Unicode text. Technologies such as ATSUI, MLTE, Quartz, and Cocoa Text all leverage Unicode in the display of text. Core Foundation and Cocoa strings also provide a way to store Unicode strings in your application. 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. With an internationalized operating system such as Mac OS X, some 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 on Mac OS X, you must use the appropriate Unicode technologies and API. The text classes in the Cocoa framework automatically provide multiscript support. For Carbon and other non-Cocoa applications, you should use the following technologies:

• Wherever possible, use CFString from Core Foundation String Services instead of C or Pascal strings.

  CFString objects internally store and handle Unicode data without requiring you to have any specific knowledge of the global character-set standard. If you need to convert between Unicode and C and Pascal strings in other encodings, use the facilities that CFString provides. However, avoid converting CFString objects to and from C strings or Pascal strings if possible. Such conversions are computationally expensive and frequently introduce bugs affecting multiscript presentation. If you cannot find any CFString or Unicode-aware API to use in a certain situation, convert the string to the application’s text encoding.

• To format dates use the CFDateFormatter interface in Core Foundation.

• To format numbers, use the CFNumberFormatter interface in Core Foundation.

• For localized strings, use Core Foundation’s CFCopyLocalizedString (and related macros) instead of GetIndString.

  Strings returned by GetIndString are specific to the current script system and thus cannot represent multiscript text. CFCopyLocalizedString returns Unicode-based CFString objects, which can represent multiscript text. Generally, your code should use dynamic text processing over static text in your code. See “Loading String Resources Into Your Code” for more information.

• Avoid directly accessing system layers below Core Services.

  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 Core Foundation URL Services (CFURL), the File Manager data type FSRef, or the NSFileManager object in Cocoa.

• Avoid using the TextEdit API.

  The TextEdit API is capable of dealing with multiscript text. However, it requires you to manage script fonts and style runs yourself. The Multilingual Text Engine (MLTE) provides a much simpler API to handle multiscript text based on Unicode.

• Never assume text data to be in the MacRoman encoding.

  You can no longer assume that all text data uses 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.

For more information on file encodings in Mac 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 strings and strings files, see “Strings Files”

---