Class

NSLocale

An object that encapsulates information about linguistic, cultural, and technological conventions and standards, such as date formats, decimal separators, and currency symbols.

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 the init(localeIdentifier:) method 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. For convenience, the autoupdatingCurrent class property provides a locale that remains up to date with the user's configuration settings:

let locale = NSLocale.autoupdatingCurrent

If you need a locale that matches the user's preferences at the moment you read it, but that doesn't change when the user makes configuration changes, use the locale found on the current property instead. If you need to be alerted when the user does make changes to region settings, register for the currentLocaleDidChangeNotification notification.

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:

let code = locale.languageCode!
let language = locale.localizedString(forLanguageCode: code)!

print("\(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 DateFormatter 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, CFLocale. See Toll-Free Bridging for more information on toll-free bridging.

Nested Types

NSLocale.LanguageDirection

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

NSLocale.Key

The keys used to access components of a locale.

Symbols

Getting and Initializing Locales

init(localeIdentifier: String)

Initializes a locale using a given locale identifier.

init?(coder: NSCoder)

Initializes a locale instance from an archive.

class var autoupdatingCurrent: Locale

A locale representing the user's current region settings.

class var current: Locale

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

class var system: Locale

A locale representing the generic root values with little localization.

class let currentLocaleDidChangeNotification: NSNotification.Name

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

Getting Information About a Locale

var localeIdentifier: String

The identifier for the locale.

var countryCode: String?

The country code for the locale.

var languageCode: String

The language code for the locale.

var scriptCode: String?

The script code for the locale.

var variantCode: String?

The variant code for the locale.

var exemplarCharacterSet: CharacterSet

The exemplar character set for the locale.

var collationIdentifier: String?

The collation identifier for the locale.

var collatorIdentifier: String

The collator identifier for the locale.

var usesMetricSystem: Bool

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

var decimalSeparator: String

The decimal separator for the locale.

var groupingSeparator: String

The grouping separator for the locale.

var currencyCode: String?

The currency code for the locale.

var currencySymbol: String

The currency symbol for the locale.

var calendarIdentifier: String

The calendar identifier for the locale.

var quotationBeginDelimiter: String

The begin quotation symbol for the locale.

var quotationEndDelimiter: String

The end quotation symbol for the locale.

var alternateQuotationBeginDelimiter: String

The alternate begin quotation symbol for the locale.

var alternateQuotationEndDelimiter: String

The alternate end quotation symbol for the locale.

Getting Display Information About a Locale

func localizedString(forLocaleIdentifier: String)

Returns the localized string for the specified locale identifier.

func localizedString(forCountryCode: String)

Returns the localized string for the specified country code.

func localizedString(forLanguageCode: String)

Returns the localized string for the specified language code.

func localizedString(forScriptCode: String)

Returns the localized string for the specified script code.

func localizedString(forVariantCode: String)

Returns the localized string for the specified variant code.

func localizedString(forCollationIdentifier: String)

Returns the localized string for the specified collation identifier.

func localizedString(forCollatorIdentifier: String)

Returns the localized string for the specified collator identifier.

func localizedString(forCurrencyCode: String)

Returns the localized string for the specified currency code.

func localizedString(forCalendarIdentifier: String)

Returns the localized string for the specified calendar identifier.

Locale Calendar Identifiers

The types of calendars.

Converting Between Identifiers

class func canonicalLocaleIdentifier(from: String)

Returns the canonical identifier for a given locale identification string.

class func components(fromLocaleIdentifier: String)

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

class func localeIdentifier(fromComponents: [String : String])

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

class func canonicalLanguageIdentifier(from: String)

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

class func localeIdentifier(fromWindowsLocaleCode: UInt32)

Returns a locale identifier from a Windows locale code.

class func windowsLocaleCode(fromLocaleIdentifier: String)

Returns a Window locale code from the locale identifier.

Getting Line and Character Direction For a Language

class func characterDirection(forLanguage: String)

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

class func lineDirection(forLanguage: String)

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

NSLocale.LanguageDirection

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

Constants

NSLocale.LanguageDirection

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

NSLocale Component Keys

The keys used to access components of a locale.

Locale Calendar Identifiers

The types of calendars.

Notifications

class let currentLocaleDidChangeNotification: NSNotification.Name

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

Type Properties

class var availableLocaleIdentifiers: [String]

The list of locale identifiers available on the system.

class var commonISOCurrencyCodes: [String]

A list of commonly encountered currency codes.

class var isoCountryCodes: [String]

The list of known country codes.

class var isoCurrencyCodes: [String]

The list of known currency codes.

class var isoLanguageCodes: [String]

The list of known language codes.

class var preferredLanguages: [String]

An ordered list of the user's preferred languages.

Instance Methods

func displayName(forKey: NSLocale.Key, value: Any)

Returns the display name for the given value.

func object(forKey: NSLocale.Key)

Returns the object corresponding to the specified key.

Relationships

Inherits From