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(locale​Identifier:​) method using one of the locale identifiers found in the available​Locale​Identifiers array. However, you usually use a locale configured to match the preferences of the current user. For convenience, the autoupdating​Current 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 current​Locale​Did​Change​Notification 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 Date​Formatter 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.Language​Direction

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(locale​Identifier:​ String)

Initializes a locale using a given locale identifier.

init?(coder:​ NSCoder)

Initializes a locale instance from an archive.

class var autoupdating​Current:​ 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 current​Locale​Did​Change​Notification:​ NSNotification.Name

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

Getting Information About a Locale

var locale​Identifier:​ String

The identifier for the locale.

var country​Code:​ String?

The country code for the locale.

var language​Code:​ String

The language code for the locale.

var script​Code:​ String?

The script code for the locale.

var variant​Code:​ String?

The variant code for the locale.

var exemplar​Character​Set:​ Character​Set

The exemplar character set for the locale.

var collation​Identifier:​ String?

The collation identifier for the locale.

var collator​Identifier:​ String

The collator identifier for the locale.

var uses​Metric​System:​ Bool

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

var decimal​Separator:​ String

The decimal separator for the locale.

var grouping​Separator:​ String

The grouping separator for the locale.

var currency​Code:​ String?

The currency code for the locale.

var currency​Symbol:​ String

The currency symbol for the locale.

var calendar​Identifier:​ String

The calendar identifier for the locale.

var quotation​Begin​Delimiter:​ String

The begin quotation symbol for the locale.

var quotation​End​Delimiter:​ String

The end quotation symbol for the locale.

var alternate​Quotation​Begin​Delimiter:​ String

The alternate begin quotation symbol for the locale.

var alternate​Quotation​End​Delimiter:​ String

The alternate end quotation symbol for the locale.

Getting Display Information About a Locale

func localized​String(for​Locale​Identifier:​ String)

Returns the localized string for the specified locale identifier.

func localized​String(for​Country​Code:​ String)

Returns the localized string for the specified country code.

func localized​String(for​Language​Code:​ String)

Returns the localized string for the specified language code.

func localized​String(for​Script​Code:​ String)

Returns the localized string for the specified script code.

func localized​String(for​Variant​Code:​ String)

Returns the localized string for the specified variant code.

func localized​String(for​Collation​Identifier:​ String)

Returns the localized string for the specified collation identifier.

func localized​String(for​Collator​Identifier:​ String)

Returns the localized string for the specified collator identifier.

func localized​String(for​Currency​Code:​ String)

Returns the localized string for the specified currency code.

func localized​String(for​Calendar​Identifier:​ String)

Returns the localized string for the specified calendar identifier.

Locale Calendar Identifiers

The types of calendars.

Converting Between Identifiers

class func canonical​Locale​Identifier(from:​ String)

Returns the canonical identifier for a given locale identification string.

class func components(from​Locale​Identifier:​ String)

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

class func locale​Identifier(from​Components:​ [String :​ String])

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

class func canonical​Language​Identifier(from:​ String)

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

class func locale​Identifier(from​Windows​Locale​Code:​ UInt32)

Returns a locale identifier from a Windows locale code.

class func windows​Locale​Code(from​Locale​Identifier:​ String)

Returns a Window locale code from the locale identifier.

Getting Line and Character Direction For a Language

class func character​Direction(for​Language:​ String)

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

class func line​Direction(for​Language:​ String)

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

NSLocale.Language​Direction

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

Constants

NSLocale.Language​Direction

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 current​Locale​Did​Change​Notification:​ NSNotification.Name

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

Type Properties

class var available​Locale​Identifiers:​ [String]

The list of locale identifiers available on the system.

class var common​ISOCurrency​Codes:​ [String]

A list of commonly encountered currency codes.

class var iso​Country​Codes:​ [String]

The list of known country codes.

class var iso​Currency​Codes:​ [String]

The list of known currency codes.

class var iso​Language​Codes:​ [String]

The list of known language codes.

class var preferred​Languages:​ [String]

An ordered list of the user's preferred languages.

Instance Methods

func display​Name(for​Key:​ NSLocale.Key, value:​ Any)

Returns the display name for the given value.

func object(for​Key:​ NSLocale.Key)

Returns the object corresponding to the specified key.