Class

NSLocale

Information about linguistic, cultural, and technological conventions for use in formatting data for presentation.

Declaration

@interface NSLocale : NSObject

Overview

You typically use a locale to format and interpret information about and according to the user’s customs and preferences.

You can initialize any number of locale instances with initWithLocaleIdentifier: using one of the locale identifiers found in the availableLocaleIdentifiers array. However, you usually use a locale configured to match the preferences of the current user.

Use the currentLocale property to get the locale matching the current user's preferences. If you need to be alerted when the user does make changes to region settings, register for the NSCurrentLocaleDidChangeNotification notification. Alternatively, you can use the autoupdatingCurrentLocale property to get a locale that automatically updates with the user's configuration settings:

NSLocale* locale = [NSLocale autoupdatingCurrentLocale];

You can inspect a locale by reading its properties, as listed in Getting Information About a Locale. For properties containing a code or identifier, you can then obtain a string suitable for presentation to the user with the methods listed in Getting Display Information About a Locale. For example, you can report the user's language as a string localized in that language using the autoupdating locale obtained in the previous example:

NSString* code = locale.languageCode;
NSString* language = [locale localizedStringForLanguageCode:code];

NSLog(@"%@",language);
// Prints "English" for locale en_US, "français" for fr_FR

You frequently use a locale in conjunction with a formatter. For example, the NSDateFormatter class has a locale property that ensures dates are converted to strings that match the user's expectations about date formatting. By default, this property indicates the user's current locale, which is usually the behavior you want, but you can instead set it to another locale instance to obtain a different output. See Data Formatting Guide for more information about working with formatters.

NSLocale is toll-free bridged with its Core Foundation counterpart, CFLocaleRef. See Toll-Free Bridging for more information on toll-free bridging.

Topics

Initializing a Locale

+ localeWithLocaleIdentifier:

Returns a locale initialized using the given locale identifier.

- initWithLocaleIdentifier:

Initializes a locale using a given locale identifier.

- initWithCoder:

Returns a locale initialized from data in the given unarchiver.

Getting the User's Locale

autoupdatingCurrentLocale

A locale which tracks the user’s current preferences.

currentLocale

A locale representing the user's region settings at the time the property is read.

NSCurrentLocaleDidChangeNotification

A notification that indicates that the user’s locale changed.

systemLocale

A locale representing the generic root values with little localization.

Getting Known Identifiers and Codes

availableLocaleIdentifiers

The list of locale identifiers available on the system.

ISOCountryCodes

The list of known country codes.

ISOLanguageCodes

The list of known language codes.

ISOCurrencyCodes

The list of known currency codes.

commonISOCurrencyCodes

A list of commonly encountered currency codes.

Converting Between Identifiers

+ canonicalLocaleIdentifierFromString:

Returns the canonical identifier for a given locale identification string.

+ componentsFromLocaleIdentifier:

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

+ localeIdentifierFromComponents:

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

+ canonicalLanguageIdentifierFromString:

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

+ localeIdentifierFromWindowsLocaleCode:

Returns a locale identifier from a Windows locale code.

+ windowsLocaleCodeFromLocaleIdentifier:

Returns a Window locale code from the locale identifier.

Getting Information About a Locale

localeIdentifier

The identifier for the locale.

countryCode

The country code for the locale.

languageCode

The language code for the locale.

scriptCode

The script code for the locale.

variantCode

The variant code for the locale.

exemplarCharacterSet

The exemplar character set for the locale.

collationIdentifier

The collation identifier for the locale.

collatorIdentifier

The collator identifier for the locale.

usesMetricSystem

A Boolean value that indicates whether the locale uses the metric system.

decimalSeparator

The decimal separator for the locale.

groupingSeparator

The grouping separator for the locale.

currencyCode

The currency code for the locale.

currencySymbol

The currency symbol for the locale.

calendarIdentifier

The calendar identifier for the locale.

quotationBeginDelimiter

The begin quotation symbol for the locale.

quotationEndDelimiter

The end quotation symbol for the locale.

alternateQuotationBeginDelimiter

The alternate begin quotation symbol for the locale.

alternateQuotationEndDelimiter

The alternate end quotation symbol for the locale.

Getting Display Information About a Locale

- localizedStringForLocaleIdentifier:

Returns the localized string for the specified locale identifier.

- localizedStringForCountryCode:

Returns the localized string for the specified country code.

- localizedStringForLanguageCode:

Returns the localized string for the specified language code.

- localizedStringForScriptCode:

Returns the localized string for the specified script code.

- localizedStringForVariantCode:

Returns the localized string for the specified variant code.

- localizedStringForCollationIdentifier:

Returns the localized string for the specified collation identifier.

- localizedStringForCollatorIdentifier:

Returns the localized string for the specified collator identifier.

- localizedStringForCurrencyCode:

Returns the localized string for the specified currency code.

- localizedStringForCalendarIdentifier:

Returns the localized string for the specified calendar identifier.

Accessing Locale Information by Key

- objectForKey:

Returns the value of the component corresponding to the specified key.

- displayNameForKey:value:

Returns the display name for the given locale component value.

NSLocaleKey

The keys used to access components of a locale.

Getting the User's Preferred Languages

preferredLanguages

An ordered list of the user's preferred languages.

Getting Line and Character Direction for a Language

+ characterDirectionForLanguage:

Returns the direction of the sequence of characters in a line for the specified ISO language code.

+ lineDirectionForLanguage:

Returns the direction of the sequence of lines for the specified ISO language code.

NSLocaleLanguageDirection

The directions that a language may take across a page of text.

Relationships

Inherits From

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software