Mac Developer Library

Developer

Foundation Framework Reference NSLocale Class Reference

Options
Deployment Target:

On This Page
Language:

NSLocale

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.4 and later.

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.

  • Initializes the receiver using a given locale identifier.

    Declaration

    Swift

    init(localeIdentifier string: String)

    Objective-C

    - (instancetype)initWithLocaleIdentifier:(NSString *)string

    Parameters

    string

    The identifier for the new locale.

    Return Value

    The initialized locale.

    Discussion

    This method is the designated initializer for this class.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Returns a locale initialized using the given locale identifier.

    Declaration

    Objective-C

    + (instancetype)localeWithLocaleIdentifier:(NSString *)string

    Parameters

    string

    The identifier for the new locale.

    Return Value

    The initialized locale.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.6 and later.

  • Returns the current logical locale for the current user.

    Declaration

    Swift

    class func autoupdatingCurrentLocale() -> NSLocale

    Objective-C

    + (NSLocale *)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.

    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).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the logical locale for the current user.

    Declaration

    Swift

    class func currentLocale() -> NSLocale

    Objective-C

    + (NSLocale *)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.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Returns the generic locale that contains fixed “backstop” settings that provide values for otherwise undefined keys.

    Declaration

    Swift

    class func systemLocale() -> NSLocale

    Objective-C

    + (NSLocale *)systemLocale

    Return Value

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

    Discussion

    Use the system locale when you don’t want any localizations. Use the current locale to format text that you display to users.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Returns the display name for the given value.

    Declaration

    Swift

    func displayNameForKey(_ key: AnyObject, value value: AnyObject) -> String?

    Objective-C

    - (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)

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    See Also

    localeIdentifier

  • The identifier for the receiver. (read-only)

    Declaration

    Swift

    var localeIdentifier: String { get }

    Objective-C

    @property(readonly, copy) NSString *localeIdentifier

    Discussion

    This may not be the same string that the locale was created with, since NSLocale may canonicalize it. Sending objectForKey: with key NSLocaleIdentifier to the locale returns the same identifier.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Returns the object corresponding to the specified key.

    Declaration

    Swift

    func objectForKey(_ key: AnyObject) -> AnyObject?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    class func preferredLanguages() -> [AnyObject]

    Objective-C

    + (NSArray *)preferredLanguages

    Return Value

    The user's preferred languages as an array of NSString objects, where each string is a language ID.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    enum NSLocaleLanguageDirection : UInt { case Unknown case LeftToRight case RightToLeft case TopToBottom case BottomToTop }

    Objective-C

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

    Constants

    • Unknown

      NSLocaleLanguageDirectionUnknown

      The direction of the language is unknown.

      Available in OS X v10.6 and later.

    • LeftToRight

      NSLocaleLanguageDirectionLeftToRight

      The language direction is from left to right.

      Available in OS X v10.6 and later.

    • RightToLeft

      NSLocaleLanguageDirectionRightToLeft

      The language direction is from right to left.

      Available in OS X v10.6 and later.

    • TopToBottom

      NSLocaleLanguageDirectionTopToBottom

      The language direction is from top to bottom.

      Available in OS X v10.6 and later.

    • BottomToTop

      NSLocaleLanguageDirectionBottomToTop

      The language direction is from bottom to top.

      Available in OS X v10.6 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    let NSLocaleIdentifier: String let NSLocaleLanguageCode: String let NSLocaleCountryCode: String let NSLocaleScriptCode: String let NSLocaleVariantCode: String let NSLocaleExemplarCharacterSet: String let NSLocaleCalendar: String let NSLocaleCollationIdentifier: String let NSLocaleUsesMetricSystem: String let NSLocaleMeasurementSystem: String let NSLocaleDecimalSeparator: String let NSLocaleGroupingSeparator: String let NSLocaleCurrencySymbol: String let NSLocaleCurrencyCode: String let NSLocaleCollatorIdentifier: String let NSLocaleQuotationBeginDelimiterKey: String let NSLocaleQuotationEndDelimiterKey: String let NSLocaleAlternateQuotationBeginDelimiterKey: String let NSLocaleAlternateQuotationEndDelimiterKey: String

    Objective-C

    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

      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.

    • NSLocaleLanguageCode

      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.

    • NSLocaleCountryCode

      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.

    • NSLocaleScriptCode

      NSLocaleScriptCode

      The key for the locale script code.

      The corresponding value is an NSString object.

      Available in OS X v10.4 and later.

    • NSLocaleVariantCode

      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.

    • NSLocaleExemplarCharacterSet

      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.

    • NSLocaleCalendar

      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.

    • NSLocaleCollationIdentifier

      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.

    • NSLocaleUsesMetricSystem

      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 NOfalse, you can typically assume American measurement units (for example, the statute mile).

      Available in OS X v10.4 and later.

    • NSLocaleMeasurementSystem

      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.

    • NSLocaleDecimalSeparator

      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.

    • NSLocaleGroupingSeparator

      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.

    • NSLocaleCurrencySymbol

      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.

    • NSLocaleCurrencyCode

      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.

    • NSLocaleCollatorIdentifier

      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.

    • NSLocaleQuotationBeginDelimiterKey

      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.

    • NSLocaleQuotationEndDelimiterKey

      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.

    • NSLocaleAlternateQuotationBeginDelimiterKey

      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.

    • NSLocaleAlternateQuotationEndDelimiterKey

      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.

  • These constants identify NSCalendar instances.

    Declaration

    Swift

    let NSGregorianCalendar: String let NSBuddhistCalendar: String let NSChineseCalendar: String let NSHebrewCalendar: String let NSIslamicCalendar: String let NSIslamicCivilCalendar: String let NSJapaneseCalendar: String let NSRepublicOfChinaCalendar: String let NSPersianCalendar: String let NSIndianCalendar: String let NSISO8601Calendar: String

    Objective-C

    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

      NSGregorianCalendar

      Identifier for the Gregorian calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSBuddhistCalendar

      NSBuddhistCalendar

      Identifier for the Buddhist calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSChineseCalendar

      NSChineseCalendar

      Identifier for the Chinese calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSHebrewCalendar

      NSHebrewCalendar

      Identifier for the Hebrew calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSIslamicCalendar

      NSIslamicCalendar

      Identifier for the Islamic calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSIslamicCivilCalendar

      NSIslamicCivilCalendar

      Identifier for the Islamic civil calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSJapaneseCalendar

      NSJapaneseCalendar

      Identifier for the Japanese calendar.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.

    • NSRepublicOfChinaCalendar

      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.

      Deprecated in OS X v10.10.

    • NSPersianCalendar

      NSPersianCalendar

      Identifier for the Persian calendar

      Available in OS X v10.6 and later.

      Deprecated in OS X v10.10.

    • NSIndianCalendar

      NSIndianCalendar

      Identifier for the Indian calendar

      Available in OS X v10.6 and later.

      Deprecated in OS X v10.10.

    • NSISO8601Calendar

      NSISO8601Calendar

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

      Available in OS X v10.6 and later.

      Deprecated in OS X v10.10.

    Discussion

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