<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 8.0.0 -",
    "macOS: 10.10.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/Locale",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "s:10Foundation6LocaleV"
  },
  "title" : "Locale"
}
-->

# Locale

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

```
struct Locale
```

## Overview

[`Locale`](/documentation/Foundation/Locale) encapsulates 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 formatting conventions for dates and times.

Apps use locales to provide, format, and interpret information about and according to the user’s customs and preferences. Data formatting APIs commonly make use of locales to present data in a locale-appropriate way.

You can create a [`Locale`](/documentation/Foundation/Locale) from a common identifier like `en-US`, or by specifying its components. More commonly, you access the current system locale with the [`current`](/documentation/Foundation/Locale/current) or [`autoupdatingCurrent`](/documentation/Foundation/Locale/autoupdatingCurrent) static variables.

### Working with locale components

A [`Locale`](/documentation/Foundation/Locale) exposes its various traits — the appropriate measurement system, currency symbols, date and time conventions, and more — as strongly-typed properties like [`currency`](/documentation/Foundation/Locale/currency-swift.property), `numberingSystem`, and `firstDayOfWeek`.

In addition, the [`language`](/documentation/Foundation/Locale/language-swift.property) property allows you examine traits of languages, through the [`Locale.Language`](/documentation/Foundation/Locale/Language-swift.struct) type, in contast with [`NSLocale`](/documentation/Foundation/NSLocale), where [`languageCode`](/documentation/Foundation/NSLocale/languageCode) is just a string identifier. You can use a locale’s language to compare whether two locales use the same language, or if one language is a parent of another.

The following example creates a [`Locale`](/documentation/Foundation/Locale) from the identifier `zh-CN`, for Chinese. It then accesses this locale’s [`language`](/documentation/Foundation/Locale/language-swift.property) to get the language’s [`script`](/documentation/Foundation/Locale/Language-swift.struct/script), and uses a US English locale to get a localized string describing the script: “Simplified Han”. With the locale `zh-Hant-CN`, for Traditional Chinese, the script would be “Traditional Han” instead.

```swift
let zhCN = Locale(identifier: "zh-CN")
if let script = zhCN.language.script {
    let enUS = Locale(identifier: "en-US")
    let localizedScript = enUS.localizedString(forScript: script) // "Simplified Han"
}
```

### Creating custom locales from components

You can create a custom locale by creating a [`Locale`](/documentation/Foundation/Locale) instance from a customized [`Locale.Components`](/documentation/Foundation/Locale/Components). Do this when you want to tweak specific aspects of a locale. The following example creates a locale that uses language conventions of British English (language region `GB`), but otherwise uses US conventions for things like currency and measurement.

```swift
var components = Locale.Components(languageCode: "en", languageRegion: "GB")
components.region = Locale.Region("US")
let en_GB_US = Locale(components: components)
```

Creating a custom locale like this isn’t necessarily common in apps, but can be useful in unit testing your app’s localizations.

## Topics

### Creating a locale by identifier

[`init(identifier:)`](/documentation/Foundation/Locale/init(identifier:))

Creates a locale with the specified identifier.

### Creating a locale by components

[`init(components:)`](/documentation/Foundation/Locale/init(components:))

Creates a locale from the given components.

[`Locale.Components`](/documentation/Foundation/Locale/Components)

A type that represents the components of a locale, for use when creating a locale with specific overrides.

[`init(languageCode:script:languageRegion:)`](/documentation/Foundation/Locale/init(languageCode:script:languageRegion:))

Creates a locale with the specified language code, script, and region identifier.

[`init(languageComponents:)`](/documentation/Foundation/Locale/init(languageComponents:))

Creates a locale from the given language components.

[`Locale.Language.Components`](/documentation/Foundation/Locale/Language-swift.struct/Components)

A type that identifies a language by its various components.

### Getting the user’s locale

[`autoupdatingCurrent`](/documentation/Foundation/Locale/autoupdatingCurrent)

A locale which tracks the user’s current preferences.

[`current`](/documentation/Foundation/Locale/current)

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

### Getting known identifiers and codes

[`availableIdentifiers`](/documentation/Foundation/Locale/availableIdentifiers)

A list of available identifiers.

[`isoRegionCodes`](/documentation/Foundation/Locale/isoRegionCodes)

A list of available region codes.

[`isoLanguageCodes`](/documentation/Foundation/Locale/isoLanguageCodes)

A list of available language codes.

[`isoCurrencyCodes`](/documentation/Foundation/Locale/isoCurrencyCodes)

A list of available currency codes.

[`commonISOCurrencyCodes`](/documentation/Foundation/Locale/commonISOCurrencyCodes)

A list of common currency codes.

### Converting between identifiers

[`canonicalIdentifier(from:)`](/documentation/Foundation/Locale/canonicalIdentifier(from:))

Returns a canonical identifier from the given string.

[`components(fromIdentifier:)`](/documentation/Foundation/Locale/components(fromIdentifier:))

Returns a dictionary that splits an identifier into its component pieces.

[`identifier(fromComponents:)`](/documentation/Foundation/Locale/identifier(fromComponents:))

Constructs an identifier from a dictionary of components.

[`identifier(_:from:)`](/documentation/Foundation/Locale/identifier(_:from:))

Returns the identifier conforming to the specified standard for the specified string.

[`Locale.IdentifierType`](/documentation/Foundation/Locale/IdentifierType)

A type that indicates the standard that defines a locale’s identifier.

[`canonicalLanguageIdentifier(from:)`](/documentation/Foundation/Locale/canonicalLanguageIdentifier(from:))

Returns a canonical language identifier from the given string.

[`identifier(fromWindowsLocaleCode:)`](/documentation/Foundation/Locale/identifier(fromWindowsLocaleCode:))

Returns the locale identifier from a given Windows locale code, or `nil` if it could not be converted.

[`windowsLocaleCode(fromIdentifier:)`](/documentation/Foundation/Locale/windowsLocaleCode(fromIdentifier:))

Returns the Windows locale code from a given identifier, or `nil` if it could not be converted.

### Getting locale components

[`Locale.Components`](/documentation/Foundation/Locale/Components)

A type that represents the components of a locale, for use when creating a locale with specific overrides.

### Getting language components

[`language`](/documentation/Foundation/Locale/language-swift.property)

The language of a locale.

[`Locale.Language`](/documentation/Foundation/Locale/Language-swift.struct)

A type that represents a language, as used in a locale.

### Getting date and time components

[`firstDayOfWeek`](/documentation/Foundation/Locale/firstDayOfWeek)

The first day of the week as represented by this locale.

[`Locale.Weekday`](/documentation/Foundation/Locale/Weekday)

A type that represents weekdays, used for indicating a locale’s first day of the week.

[`hourCycle`](/documentation/Foundation/Locale/hourCycle-swift.property)

The hour cycle used by the locale, like one-to-twelve or zero-to-twenty-three.

[`Locale.HourCycle`](/documentation/Foundation/Locale/HourCycle-swift.enum)

A type that represents the hour cycle used in a locale, like one-to-twelve or zero-to-twenty-three.

[`timeZone`](/documentation/Foundation/Locale/timeZone)

The time zone associated with the locale, if any.

### Getting measurement and counting components

[`currency`](/documentation/Foundation/Locale/currency-swift.property)

The currency used by the locale.

[`Locale.Currency`](/documentation/Foundation/Locale/Currency-swift.struct)

A type that represents the currency system used by a locale, like dollars or euros.

[`measurementSystem`](/documentation/Foundation/Locale/measurementSystem-swift.property)

The measurement system used by the locale, like metric or the US system.

[`Locale.MeasurementSystem`](/documentation/Foundation/Locale/MeasurementSystem-swift.struct)

A type that represents the measurement system used by a locale, like metric or the US system.

[`numberingSystem`](/documentation/Foundation/Locale/numberingSystem-swift.property)

The numbering system used by the locale.

[`availableNumberingSystems`](/documentation/Foundation/Locale/availableNumberingSystems)

An array containing all the valid numbering systems for the locale.

[`Locale.NumberingSystem`](/documentation/Foundation/Locale/NumberingSystem-swift.struct)

A type that represents the numbering system used in a locale.

### Getting region components

[`region`](/documentation/Foundation/Locale/region-swift.property)

The region used by the locale.

[`Locale.Region`](/documentation/Foundation/Locale/Region-swift.struct)

A type that represents a geographic region, for use in specifying a locale or language.

[`subdivision`](/documentation/Foundation/Locale/subdivision-swift.property)

The optional subdivision of the region used by this locale.

[`Locale.Subdivision`](/documentation/Foundation/Locale/Subdivision-swift.struct)

A type that represents a subdivision of a region, such as a state in the US or a province in Canada.

[`variant`](/documentation/Foundation/Locale/variant-swift.property)

An optional variant used by the locale.

[`Locale.Variant`](/documentation/Foundation/Locale/Variant-swift.struct)

A type that represents a locale’s language variant.

### Getting ordering components

[`collation`](/documentation/Foundation/Locale/collation-swift.property)

The string sort order of the locale.

[`Locale.Collation`](/documentation/Foundation/Locale/Collation-swift.struct)

A type that represents the string sort order used by the locale.

### Getting information about a locale

[`identifier`](/documentation/Foundation/Locale/identifier)

The identifier of the locale.

[`identifier(_:)`](/documentation/Foundation/Locale/identifier(_:))

Returns the locale identifier, in the specified standard format.

[`Locale.IdentifierType`](/documentation/Foundation/Locale/IdentifierType)

A type that indicates the standard that defines a locale’s identifier.

[`calendar`](/documentation/Foundation/Locale/calendar)

The calendar for the locale, or the Gregorian calendar as a fallback.

[`regionCode`](/documentation/Foundation/Locale/regionCode)

The region code of the locale, or `nil` if it has none.

[`languageCode`](/documentation/Foundation/Locale/languageCode-swift.property)

The language code of the locale, or `nil` if has none.

[`scriptCode`](/documentation/Foundation/Locale/scriptCode)

The script code of the locale, or `nil` if has none.

[`variantCode`](/documentation/Foundation/Locale/variantCode)

The variant code for the locale, or `nil` if it has none.

[`exemplarCharacterSet`](/documentation/Foundation/Locale/exemplarCharacterSet)

The exemplar character set for the locale, or `nil` if has none.

[`collationIdentifier`](/documentation/Foundation/Locale/collationIdentifier)

The collation identifier for the locale, or `nil` if it has none.

[`collatorIdentifier`](/documentation/Foundation/Locale/collatorIdentifier)

The collator identifier of the locale.

[`usesMetricSystem`](/documentation/Foundation/Locale/usesMetricSystem)

A Boolean that is true if the locale uses the metric system.

[`decimalSeparator`](/documentation/Foundation/Locale/decimalSeparator)

The decimal separator of the locale.

[`groupingSeparator`](/documentation/Foundation/Locale/groupingSeparator)

The grouping separator of the locale.

[`currencyCode`](/documentation/Foundation/Locale/currencyCode)

The currency code of the locale.

[`currencySymbol`](/documentation/Foundation/Locale/currencySymbol)

The currency symbol of the locale.

[`quotationBeginDelimiter`](/documentation/Foundation/Locale/quotationBeginDelimiter)

The quotation begin delimiter of the locale.

[`quotationEndDelimiter`](/documentation/Foundation/Locale/quotationEndDelimiter)

The quotation end delimiter of the locale.

[`alternateQuotationBeginDelimiter`](/documentation/Foundation/Locale/alternateQuotationBeginDelimiter)

The alternate quotation begin delimiter of the locale.

[`alternateQuotationEndDelimiter`](/documentation/Foundation/Locale/alternateQuotationEndDelimiter)

The alternate quotation end delimiter of the locale.

### Getting display information about a locale

[`localizedString(for:)`](/documentation/Foundation/Locale/localizedString(for:))

Returns a localized string for a specified calendar.

[`localizedString(forCollationIdentifier:)`](/documentation/Foundation/Locale/localizedString(forCollationIdentifier:))

Returns a localized string for a specified ICU collation identifier.

[`localizedString(forCollatorIdentifier:)`](/documentation/Foundation/Locale/localizedString(forCollatorIdentifier:))

Returns a localized string for a specified ICU collator identifier.

[`localizedString(forCurrencyCode:)`](/documentation/Foundation/Locale/localizedString(forCurrencyCode:))

Returns a localized string for a specified ISO 4217 currency code.

[`localizedString(forIdentifier:)`](/documentation/Foundation/Locale/localizedString(forIdentifier:))

Returns a localized string for a specified locale identifier.

[`localizedString(forLanguageCode:)`](/documentation/Foundation/Locale/localizedString(forLanguageCode:))

Returns a localized string for a specified language code.

[`localizedString(forRegionCode:)`](/documentation/Foundation/Locale/localizedString(forRegionCode:))

Returns a localized string for a specified region code.

[`localizedString(forScriptCode:)`](/documentation/Foundation/Locale/localizedString(forScriptCode:))

Returns a localized string for a specified script code.

[`localizedString(forVariantCode:)`](/documentation/Foundation/Locale/localizedString(forVariantCode:))

Returns a localized string for a specified variant code.

### Getting the user’s preferred languages

[`preferredLanguages`](/documentation/Foundation/Locale/preferredLanguages)

A list of the user’s preferred languages.

### Getting line and character direction for a language

[`characterDirection(forLanguage:)`](/documentation/Foundation/Locale/characterDirection(forLanguage:))

Returns the character direction for a specified language code.

[`lineDirection(forLanguage:)`](/documentation/Foundation/Locale/lineDirection(forLanguage:))

Returns the line direction for a specified language code.

[`Locale.LanguageDirection`](/documentation/Foundation/Locale/LanguageDirection)

An alias for the standard set of language directions.

[`NSLocale.LanguageDirection`](/documentation/Foundation/NSLocale/LanguageDirection)

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

### Working with notification messages

[`Locale.CurrentLocaleDidChangeMessage`](/documentation/Foundation/Locale/CurrentLocaleDidChangeMessage)

A message the system sends when the current locale changes.

### Using reference types

[`NSLocale`](/documentation/Foundation/NSLocale)

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


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)