NSLocale Class Reference

Inherits from	NSObject
Conforms to	NSCopying NSSecureCoding NSObject (NSObject)
Framework	/System/Library/Frameworks/Foundation.framework
Availability	Available in iOS 2.0 and later.
Declared in	NSLocale.h
Companion guides	Locales Programming Guide Data Formatting Guide
Related sample code	AVMovieExporter AVPlayerDemo CoreTelephonyDemo International Mountains SimpleStocks

Overview

Locales encapsulate information about linguistic, cultural, and technological conventions and standards. Examples of information encapsulated by a locale include the symbol used for the decimal separator in numbers and the way dates are formatted.

Locales are typically used to provide, format, and interpret information about and according to the user’s customs and preferences. They are frequently used in conjunction with formatters (see Data Formatting Guide). Although you can use many locales, you usually use the one associated with the current user.

NSLocale is “toll-free bridged” with its Core Foundation counterpart, CFLocale. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSLocale * parameter, you can pass a CFLocaleRef, and in a function where you see a CFLocaleRef parameter, you can pass an NSLocale instance (you cast one type to the other to suppress compiler warnings). See “Toll-Free Bridging” for more information on toll-free bridging.

Tasks

Getting and Initializing Locales

Getting Information About a Locale

Getting System Locale Information

Converting Between Identifiers

Getting Preferred Languages

Getting Line and Character Direction For a Language

Class Methods

autoupdatingCurrentLocale

Returns the current logical locale for the current user.

+ (id)autoupdatingCurrentLocale

Return Value

The current logical locale for the current user. The locale is formed from the settings for the current user’s chosen system locale overlaid with any custom settings the user has specified in System Preferences.

The object always reflects the current state of the current user’s locale settings.

Discussion

Settings you get from this locale do change as the user’s settings change (contrast with currentLocale).

Note that if you cache values based on the locale or related information, those caches will of course not be automatically updated by the updating of the locale object. You can recompute caches upon receipt of the notification (NSCurrentLocaleDidChangeNotification) that gets sent out for locale changes (see Notification Programming Topics to learn how to register for and receive notifications).

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

availableLocaleIdentifiers

Returns an array of NSString objects, each of which identifies a locale available on the system.

+ (NSArray *)availableLocaleIdentifiers

Return Value

An array of NSString objects, each of which identifies a locale available on the system.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

canonicalLanguageIdentifierFromString:

Returns a canonical language identifier by mapping an arbitrary locale identification string to the canonical identifier.

+ (NSString *)canonicalLanguageIdentifierFromString:(NSString *)string

Parameters

string: A string representation of an arbitrary locale identifier.

Return Value

A string that represents the canonical language identifier for the specified arbitrary locale identifier.

Availability

Available in iOS 4.0 and later.

Declared In

NSLocale.h

canonicalLocaleIdentifierFromString:

Returns the canonical identifier for a given locale identification string.

+ (NSString *)canonicalLocaleIdentifierFromString:(NSString *)string

Parameters

string: A locale identification string.

Return Value

The canonical identifier for an the locale identified by string.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

characterDirectionForLanguage:

Returns the character direction for the specified ISO language code.

+ (NSLocaleLanguageDirection)characterDirectionForLanguage:(NSString *)isoLangCode

Parameters

isoLangCode: The ISO language code.

Return Value

Returns the character direction for the language. See “NSLocaleLanguageDirection” for possible values. If the appropriate direction can’t be determined NSLocaleLanguageDirectionUnknown is returned.

Availability

Available in iOS 4.0 and later.

Declared In

NSLocale.h

commonISOCurrencyCodes

Returns an array of common ISO currency codes

+ (NSArray *)commonISOCurrencyCodes

Return Value

An array of NSString objects that represents common ISO currency codes.

Discussion

Common codes may include, for example, AED, AUD, BZD, DKK, EUR, GBP, JPY, KES, MXN, OMR, STD, USD, XCD, and ZWD.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

componentsFromLocaleIdentifier:

Returns a dictionary that is the result of parsing a locale ID.

+ (NSDictionary *)componentsFromLocaleIdentifier:(NSString *)string

Parameters

string: A locale ID, consisting of language, script, country, variant, and keyword/value pairs, for example, "en_US@calendar=japanese".

Return Value

A dictionary that is the result of parsing string as a locale ID. The keys are the constant NSString constants corresponding to the locale ID components, and the values correspond to constants where available. For the complete set of dictionary keys, see “Constants.”

Discussion

For example: the locale ID "en_US@calendar=japanese" yields a dictionary with three entries: NSLocaleLanguageCode=en, NSLocaleCountryCode=US, and NSLocaleCalendar=NSJapaneseCalendar.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

currentLocale

Returns the logical locale for the current user.

+ (id)currentLocale

Return Value

The logical locale for the current user. The locale is formed from the settings for the current user’s chosen system locale overlaid with any custom settings the user has specified in System Preferences.

Discussion

Settings you get from this locale do not change as a user’s Preferences are changed so that your operations are consistent. Typically you perform some operations on the returned object and then allow it to be disposed of. Moreover, since the returned object may be cached, you do not need to hold on to it indefinitely. Contrast with autoupdatingCurrentLocale.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

NSLocale.h

ISOCountryCodes

Returns an array of NSString objects that represents all known legal country codes.

+ (NSArray *)ISOCountryCodes

Return Value

An array of NSString objects that represents all known legal country codes.

Discussion

Note that many of country codes do not have any supporting locale data in OS X.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

ISOCurrencyCodes

Returns an array of NSString objects that represents all known legal ISO currency codes.

+ (NSArray *)ISOCurrencyCodes

Return Value

An array of NSString objects that represents all known legal ISO currency codes.

Discussion

Note that some of the currency codes may not have any supporting locale data in OS X.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

ISOLanguageCodes

Returns an array of NSString objects that represents all known legal ISO language codes.

+ (NSArray *)ISOLanguageCodes

Return Value

An array of NSString objects that represents all known legal ISO language codes.

Discussion

Note that many of the language codes do not have any supporting locale data in OS X.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

lineDirectionForLanguage:

Returns the line direction for the specified ISO language code.

+ (NSLocaleLanguageDirection)lineDirectionForLanguage:(NSString *)isoLangCode

Parameters

isoLangCode: The ISO language code.

Return Value

Returns the line direction for the language. See “NSLocaleLanguageDirection” for possible values. If the appropriate direction can’t be determined NSLocaleLanguageDirectionUnknown is returned.

Availability

Available in iOS 4.0 and later.

Declared In

NSLocale.h

localeIdentifierFromComponents:

Returns a locale identifier from the components specified in a given dictionary.

+ (NSString *)localeIdentifierFromComponents:(NSDictionary *)dict

Parameters

dict: A dictionary containing components that specify a locale. For valid dictionary keys, see “Constants.”

Return Value

A locale identifier created from the components specified in dict.

Discussion

This reverses the actions of componentsFromLocaleIdentifier:, so for example the dictionary {NSLocaleLanguageCode="en", NSLocaleCountryCode="US", NSLocaleCalendar=NSJapaneseCalendar} becomes "en_US@calendar=japanese".

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

localeIdentifierFromWindowsLocaleCode:

Returns a locale identifier from a Windows locale code.

+ (NSString *)localeIdentifierFromWindowsLocaleCode:(uint32_t)lcid

Parameters

lcid: The Windows locale code.

Return Value

The locale identifier.

Availability

Available in iOS 4.0 and later.

Declared In

NSLocale.h

preferredLanguages

Returns the user's language preference order as an array of strings.

+ (NSArray *)preferredLanguages

Return Value

The user's language preference order as an array of NSString objects, each of which is a canonicalized IETF BCP 47 language identifier.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

NSLocale.h

systemLocale

Returns the “root”, canonical locale, that contains fixed “backstop” settings that provide values for otherwise undefined keys.

+ (id)systemLocale

Return Value

The “root”, canonical locale, that contains fixed “backstop” settings that provide values for otherwise undefined keys.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

windowsLocaleCodeFromLocaleIdentifier:

Returns a Window locale code from the locale identifier.

+ (uint32_t)windowsLocaleCodeFromLocaleIdentifier:(NSString *)localeIdentifier

Parameters

localeIdentifier: The locale identifier.

Return Value

The Windows locale code.

Availability

Available in iOS 4.0 and later.

Declared In

NSLocale.h

Instance Methods

displayNameForKey:value:

Returns the display name for the given value.

- (NSString *)displayNameForKey:(id)key value:(id)value

Parameters

key: Specifies which of the locale property keys value is (see “Constants”),
value: A value for key.

Return Value

The display name for value.

Discussion

Not all locale property keys have values with display name values.

You can use the NSLocaleIdentifier key to get the name of a locale in the language of another locale, as illustrated in the following examples. The first uses the fr_FR locale.

NSLocale *frLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"fr_FR"];

NSString *displayNameString = [frLocale displayNameForKey:NSLocaleIdentifier value:@"fr_FR"];

NSLog(@"displayNameString fr_FR: %@", displayNameString);

displayNameString = [frLocale displayNameForKey:NSLocaleIdentifier value:@"en_US"];

NSLog(@"displayNameString en_US: %@", displayNameString);

returns

displayNameString fr_FR: français (France)

displayNameString en_US: anglais (États-Unis)

The following example uses the en_GB locale.

NSLocale *gbLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_GB"];

displayNameString = [gbLocale displayNameForKey:NSLocaleIdentifier value:@"fr_FR"];

NSLog(@"displayNameString fr_FR: %@", displayNameString);

displayNameString = [gbLocale displayNameForKey:NSLocaleIdentifier value:@"en_US"];

NSLog(@"displayNameString en_US: %@", displayNameString);

returns

displayNameString fr_FR: French (France)

displayNameString en_US: English (United States)

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

initWithLocaleIdentifier:

Initializes the receiver using a given locale identifier.

- (id)initWithLocaleIdentifier:(NSString *)string

Parameters

string: The identifier for the new locale.

Return Value

The initialized locale.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

NSLocale.h

localeIdentifier

Returns the identifier for the receiver.

- (NSString *)localeIdentifier

Return Value

The identifier for the receiver. This may not be the same string that the locale was created with, since NSLocale may canonicalize it.

Discussion

Equivalent to sending objectForKey: with key NSLocaleIdentifier.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

objectForKey:

Returns the object corresponding to the specified key.

- (id)objectForKey:(id)key

Parameters

key: The key for which to return the corresponding value. For valid values of key, see “Constants.”

Return Value

The object corresponding to key.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

Constants

NSLocaleLanguageDirection

These constants describe the text direction for a language. Used by the methods lineDirectionForLanguage: and characterDirectionForLanguage:.

enum {
   NSLocaleLanguageDirectionUnknown = kCFLocaleLanguageDirectionUnknown,
   NSLocaleLanguageDirectionLeftToRight = kCFLocaleLanguageDirectionLeftToRight,
   NSLocaleLanguageDirectionRightToLeft = kCFLocaleLanguageDirectionRightToLeft,
   NSLocaleLanguageDirectionTopToBottom = kCFLocaleLanguageDirectionTopToBottom,
   NSLocaleLanguageDirectionBottomToTop = kCFLocaleLanguageDirectionBottomToTop
};
typedef NSUInteger NSLocaleLanguageDirection;

Constants

NSLocaleLanguageDirectionUnknown

The direction of the language is unknown.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionLeftToRight

The language direction is from left to right.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionRightToLeft

The language direction is from right to left.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionTopToBottom

The language direction is from top to bottom.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionBottomToTop

The language direction is from bottom to top.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocale Component Keys

The following constants specify keys used to retrieve components of a locale with objectForKey:.

NSString * const NSLocaleIdentifier;
NSString * const NSLocaleLanguageCode;
NSString * const NSLocaleCountryCode;
NSString * const NSLocaleScriptCode;
NSString * const NSLocaleVariantCode;
NSString * const NSLocaleExemplarCharacterSet;
NSString * const NSLocaleCalendar;
NSString * const NSLocaleCollationIdentifier;
NSString * const NSLocaleUsesMetricSystem;
NSString * const NSLocaleMeasurementSystem;
NSString * const NSLocaleDecimalSeparator;
NSString * const NSLocaleGroupingSeparator;
NSString * const NSLocaleCurrencySymbol;
NSString * const NSLocaleCurrencyCode;
NSString * const NSLocaleCollatorIdentifier;
NSString * const NSLocaleQuotationBeginDelimiterKey;
NSString * const NSLocaleQuotationEndDelimiterKey;
NSString * const NSLocaleAlternateQuotationBeginDelimiterKey;
NSString * const NSLocaleAlternateQuotationEndDelimiterKey;

Constants

NSLocaleIdentifier

The key for the locale identifier.

The corresponding value is an NSString object. An example value might be "es_ES_PREEURO".

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleLanguageCode

The key for the locale language code.

The corresponding value is an NSString object. An example value might be "es".

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleCountryCode

The key for the locale country code.

The corresponding value is an NSString object. An example value might be "ES".

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleScriptCode

The key for the locale script code.

The corresponding value is an NSString object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleVariantCode

The key for the locale variant code.

The corresponding value is an NSString object. An example value might be "PREEURO".

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleExemplarCharacterSet

The key for the exemplar character set for the locale.

The corresponding value is an NSCharacterSet object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleCalendar

The key for the calendar associated with the locale.

The corresponding value is an NSCalendar object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleCollationIdentifier

The key for the collation associated with the locale.

The corresponding value is an NSString object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleUsesMetricSystem

The key for the flag that indicates whether the locale uses the metric system.

The corresponding value is a Boolean NSNumber object. If the value is NO, you can typically assume American measurement units (for example, the statute mile).

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleMeasurementSystem

The key for the measurement system associated with the locale.

The corresponding value is an NSString object containing a description of the measurement system used by the locale, for example “Metric” or “U.S.”.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleDecimalSeparator

The key for the decimal separator associated with the locale.

The corresponding value is an NSString object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleGroupingSeparator

The key for the numeric grouping separator associated with the locale.

The corresponding value is an NSString object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleCurrencySymbol

The key for the currency symbol associated with the locale.

The corresponding value is an NSString object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleCurrencyCode

The key for the currency code associated with the locale.

The corresponding value is an NSString object.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSLocaleCollatorIdentifier

The key for the collation identifier for the locale.

The corresponding value is an NSString object. If unknown, nil is returned.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleQuotationBeginDelimiterKey

The key for the begin quotation symbol associated with the locale.

The corresponding value is an NSString object.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleQuotationEndDelimiterKey

The key for the end quotation symbol associated with the locale.

The corresponding value is an NSString object.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleAlternateQuotationBeginDelimiterKey

The key for the alternating begin quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate. Thus, NSLocaleQuotationBeginDelimiterKey, then NSLocaleAlternateQuotationBeginDelimiterKey, etc.

The corresponding value is an NSString object.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocaleAlternateQuotationEndDelimiterKey

The key for the alternate end quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate. Thus, NSLocaleQuotationEndDelimiterKey, then NSLocaleAlternateQuotationEndDelimiterKey, etc.

The corresponding value is an NSString object.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSLocale Calendar Keys

These constants identify NSCalendar instances.

NSString * const NSGregorianCalendar;
NSString * const NSBuddhistCalendar;
NSString * const NSChineseCalendar;
NSString * const NSHebrewCalendar;
NSString * const NSIslamicCalendar;
NSString * const NSIslamicCivilCalendar;
NSString * const NSJapaneseCalendar;
NSString * const NSRepublicOfChinaCalendar;
NSString * const NSPersianCalendar;
NSString * const NSIndianCalendar;
NSString * const NSISO8601Calendar;

Constants

NSGregorianCalendar

Identifier for the Gregorian calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSBuddhistCalendar

Identifier for the Buddhist calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSChineseCalendar

Identifier for the Chinese calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSHebrewCalendar

Identifier for the Hebrew calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSIslamicCalendar

Identifier for the Islamic calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSIslamicCivilCalendar

Identifier for the Islamic civil calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSJapaneseCalendar

Identifier for the Japanese calendar.

Available in iOS 2.0 and later.

Declared in NSLocale.h.

NSRepublicOfChinaCalendar

Identifier for the Republic of China (Taiwan) calendar.

A Chinese calendar can be created, and you can do calendrical calculations with it, but you should not use it for formatting as the necessary underlying functionality is not working correctly yet.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSPersianCalendar

Identifier for the Persian calendar

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSIndianCalendar

Identifier for the Indian calendar

Available in iOS 4.0 and later.

Declared in NSLocale.h.

NSISO8601Calendar

Identifier for the ISO8601. The ISO8601 calendar is not yet implemented.

Available in iOS 4.0 and later.

Declared in NSLocale.h.

Discussion

You use these identifiers to initialize a new NSCalendar object, using initWithCalendarIdentifier:. The calendarIdentifier method returns one of these values.

Notifications

NSCurrentLocaleDidChangeNotification

Notification that indicates that the user’s locale changed.

Availability

Available in iOS 2.0 and later.

Declared In

NSLocale.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

NSLocale Class Reference

Overview

Tasks

Getting and Initializing Locales

Getting Information About a Locale

Getting System Locale Information

Converting Between Identifiers

Getting Preferred Languages

Getting Line and Character Direction For a Language

Class Methods

autoupdatingCurrentLocale

Return Value

Discussion

Availability

See Also

Declared In

availableLocaleIdentifiers

Return Value

Availability

See Also

Declared In

canonicalLanguageIdentifierFromString:

Parameters

Return Value

Availability

Declared In

canonicalLocaleIdentifierFromString:

Parameters

Return Value

Availability

See Also

Declared In

characterDirectionForLanguage:

Parameters

Return Value

Availability

See Also

Declared In

commonISOCurrencyCodes

Return Value

Discussion

Availability

See Also

Declared In

componentsFromLocaleIdentifier:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

currentLocale

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

ISOCountryCodes

Return Value

Discussion

Availability

See Also

Declared In

ISOCurrencyCodes

Return Value

Discussion

Availability

See Also

Declared In

ISOLanguageCodes

Return Value

Discussion

Availability

See Also

Declared In

lineDirectionForLanguage:

Parameters

Return Value

Availability