Internationalizing Your Application
Ideally, the text, images, and other content that iPhone applications display to users should be localized for multiple languages. The text that an alert dialog displays, for example, should be in the preferred language of the user. The process of preparing a project for content localized for particular languages is called internationalization.
Project components that are candidates for localization include:
=> Code-generated text, including locale-specific aspects of date, time, and number formatting
=> Static text—for example, an HTML file loaded into a web view for displaying application help
=> Icons (including your application icon) and other images when those images either contain text or have some culture-specific meaning
=> Sound files containing spoken language
=> Nib files
Using the Settings application, users select the language they want to see in their applications’ user interfaces from the Language preferences view. They get to this view from the International group of settings, accessed from General settings.
Figure: The Language preference view
=> Code-generated text, including locale-specific aspects of date, time, and number formatting
=> Static text—for example, an HTML file loaded into a web view for displaying application help
=> Icons (including your application icon) and other images when those images either contain text or have some culture-specific meaning
=> Sound files containing spoken language
=> Nib files
Using the Settings application, users select the language they want to see in their applications’ user interfaces from the Language preferences view. They get to this view from the International group of settings, accessed from General settings.
Figure: The Language preference view
The chosen language is associated with a subdirectory of the bundle. The subdirectory name has two components: an ISO 639-1 language code and a .lproj suffix. For example, to designate resources localized to English, the bundle would be named en.lproj. By convention, these language-localized subdirectories are called lproj directories.
Note: You may use ISO 639-2 language codes instead of those defined by ISO 639-1. However, you should should not include region codes (as defined by the ISO 3166-1 conventions) when naming your lproj
directories. Although region information is used for formatting dates, numbers, and other types of information, it is not taken into consideration when choosing which language directory to use. For more information about language and region codes, see “Language and Locale Designations” in Internationalization Programming Topics.
An lproj directory contains all the localized content for a given language. You use the facilities of the NSBundle class or the CFBundleRef opaque type to locate (in one of the application’s lproj directories) resources localized for the currently selected language. Listing 1-3 gives an example of such a directory containing content localized for English (en).
Note: You may use ISO 639-2 language codes instead of those defined by ISO 639-1. However, you should should not include region codes (as defined by the ISO 3166-1 conventions) when naming your lproj
directories. Although region information is used for formatting dates, numbers, and other types of information, it is not taken into consideration when choosing which language directory to use. For more information about language and region codes, see “Language and Locale Designations” in Internationalization Programming Topics.
An lproj directory contains all the localized content for a given language. You use the facilities of the NSBundle class or the CFBundleRef opaque type to locate (in one of the application’s lproj directories) resources localized for the currently selected language. Listing 1-3 gives an example of such a directory containing content localized for English (en).
The contents of a language-localized subdirectory
en.lproj/
InfoPlist.strings
Localizable.strings
sign.png
This subdirectory example has the following items:
=> The InfoPlist.strings file contains strings assigned as localized values of certain properties in the project’s Info.plist file (such as CFBundleDisplayName). For example, the CFBundleDisplayName key for an application named Battleship in the English version would have this entry in InfoPlist.strings in the fr.lproj subdirectory:
CFBundleDisplayName = "Cuirassé";
=> The Localizable.strings file contains localized versions of strings generated by application code.
=> The sign.png file in this example is a file containing a localized image.
To internationalize strings in your code for localization, use the NSLocalizedString macro in place of the string. This macro has the following declaration:
NSString *NSLocalizedString(NSString *key, NSString *comment);
The first parameter is a unique key to a localized string in a Localizable.strings file in a given lproj directory. The second parameter is a comment that indicates how the string is used and therefore provides additional context to the translator. For example, suppose you are setting the content of a label (UILabel object) in your user interface. The following code would internationalize the label’s text:
label.text = NSLocalizedString(@"City", @"Label for City text field");
You can then create a Localizable.strings file for a given language and add it to the proper lproj directory. For the above key, this file would have an entry similar to the following:
"City" = "Ville";
Note: Alternatively, you can insert NSLocalizedString calls in your code where appropriate and then run the genstrings command-line tool. This tool generates a Localizable.strings template that includes the key and comment for each string requiring translation.
en.lproj/
InfoPlist.strings
Localizable.strings
sign.png
This subdirectory example has the following items:
=> The InfoPlist.strings file contains strings assigned as localized values of certain properties in the project’s Info.plist file (such as CFBundleDisplayName). For example, the CFBundleDisplayName key for an application named Battleship in the English version would have this entry in InfoPlist.strings in the fr.lproj subdirectory:
CFBundleDisplayName = "Cuirassé";
=> The Localizable.strings file contains localized versions of strings generated by application code.
=> The sign.png file in this example is a file containing a localized image.
To internationalize strings in your code for localization, use the NSLocalizedString macro in place of the string. This macro has the following declaration:
NSString *NSLocalizedString(NSString *key, NSString *comment);
The first parameter is a unique key to a localized string in a Localizable.strings file in a given lproj directory. The second parameter is a comment that indicates how the string is used and therefore provides additional context to the translator. For example, suppose you are setting the content of a label (UILabel object) in your user interface. The following code would internationalize the label’s text:
label.text = NSLocalizedString(@"City", @"Label for City text field");
You can then create a Localizable.strings file for a given language and add it to the proper lproj directory. For the above key, this file would have an entry similar to the following:
"City" = "Ville";
Note: Alternatively, you can insert NSLocalizedString calls in your code where appropriate and then run the genstrings command-line tool. This tool generates a Localizable.strings template that includes the key and comment for each string requiring translation.
No comments:
Post a Comment