NSLocale Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.4 and later.
Declared in
NSLocale.h
Companion guides
Related sample code

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 OS X v10.5 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 OS X v10.4 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 OS X v10.6 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 OS X v10.4 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 OS X v10.6 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 OS X v10.5 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 OS X v10.4 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 OS X v10.4 and later.
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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.6 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 OS X v10.4 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 OS X v10.6 and later.
Declared In
NSLocale.h

localeWithLocaleIdentifier:

Returns a locale initialized using the given locale identifier.

+ (instancetype)localeWithLocaleIdentifier:(NSString *)string
Parameters
string

The identifier for the new locale.

Return Value

The initialized locale.

Availability
  • Available in OS X v10.6 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 OS X v10.5 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 OS X v10.4 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 OS X v10.6 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 OS X v10.4 and later.
Declared In
NSLocale.h

initWithLocaleIdentifier:

Initializes the receiver using a given locale identifier.

- (instancetype)initWithLocaleIdentifier:(NSString *)string
Parameters
string

The identifier for the new locale.

Return Value

The initialized locale.

Availability
  • Available in OS X v10.4 and later.
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 OS X v10.4 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 OS X v10.4 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 OS X v10.6 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionLeftToRight

The language direction is from left to right.

Available in OS X v10.6 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionRightToLeft

The language direction is from right to left.

Available in OS X v10.6 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionTopToBottom

The language direction is from top to bottom.

Available in OS X v10.6 and later.

Declared in NSLocale.h.

NSLocaleLanguageDirectionBottomToTop

The language direction is from bottom to top.

Available in OS X v10.6 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 and later.

Declared in NSLocale.h.

NSLocaleScriptCode

The key for the locale script code.

The corresponding value is an NSString object.

Available in OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.6 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 OS X v10.6 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 OS X v10.6 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 OS X v10.6 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 OS X v10.6 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 OS X v10.4 and later.

Declared in NSLocale.h.

NSBuddhistCalendar

Identifier for the Buddhist calendar.

Available in OS X v10.4 and later.

Declared in NSLocale.h.

NSChineseCalendar

Identifier for the Chinese calendar.

Available in OS X v10.4 and later.

Declared in NSLocale.h.

NSHebrewCalendar

Identifier for the Hebrew calendar.

Available in OS X v10.4 and later.

Declared in NSLocale.h.

NSIslamicCalendar

Identifier for the Islamic calendar.

Available in OS X v10.4 and later.

Declared in NSLocale.h.

NSIslamicCivilCalendar

Identifier for the Islamic civil calendar.

Available in OS X v10.4 and later.

Declared in NSLocale.h.

NSJapaneseCalendar

Identifier for the Japanese calendar.

Available in OS X v10.4 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 OS X v10.6 and later.

Declared in NSLocale.h.

NSPersianCalendar

Identifier for the Persian calendar

Available in OS X v10.6 and later.

Declared in NSLocale.h.

NSIndianCalendar

Identifier for the Indian calendar

Available in OS X v10.6 and later.

Declared in NSLocale.h.

NSISO8601Calendar

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

Available in OS X v10.6 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
Declared In
NSLocale.h