Skip to content

NSLocale ​

NSLocale represents a locale: a language, plus a country or region, and the formats that go with them — currency, decimal and grouping separators, calendar, quotation marks, and metric or imperial units.

Read the user's settings from three static properties:

iOS splits language and region into two separate settings, so a user can set "language English, region China". "Which language to show the interface in" and "which format to write amounts and dates in" therefore come from different places: the former from the language of currentLocale, the latter from its region and formats.

When the user changes the region settings, application fires the localechange event.

Inheritance: EventTarget → NSObject → NSLocale

Constructor ​

NSLocale()

Creates a locale from a locale identifier, for example new NSLocale('de_DE').

Static properties ​

PropertyDescription
preferredLanguages read-onlyThe languages the user has ordered in Settings
currentLocale read-onlyThe locale the app uses, as of the moment it is read
autoupdatingCurrentLocale read-onlyThe locale the app uses, with values that follow the settings
systemLocale read-onlyA generic locale that belongs to no language or region
availableLocaleIdentifiers read-onlyEvery locale identifier the system recognizes
ISOLanguageCodes read-onlyEvery language code
ISOCountryCodes read-onlyEvery country and region code
ISOCurrencyCodes read-onlyEvery currency code
commonISOCurrencyCodes read-onlyCommonly used currency codes

Static methods ​

MethodDescription
localeWithLocaleIdentifier()Creates a locale from a locale identifier, same as new
canonicalLocaleIdentifierFromString()Rewrites a locale identifier with canonical capitalization
canonicalLanguageIdentifierFromString()Rewrites a locale identifier as a canonical language identifier
characterDirectionForLanguage()The direction a language's characters run within a line
lineDirectionForLanguage()The direction a language's lines are laid out

Instance properties ​

Also inherits the properties of NSObject. All of the properties below are read-only.

Language and region:

PropertyDescription
localeIdentifierThe locale identifier, such as 'de_DE'
languageCodeThe language code, such as 'de'
languageIdentifierThe language identifier, such as 'de-DE'
regionCodeThe country or region code, such as 'DE'; may be null
scriptCodeThe script code, such as 'Hant'; may be null
variantCodeThe variant code; may be null

Formats:

PropertyDescription
currencyCodeThe currency code, such as 'EUR'; may be null
currencySymbolThe currency symbol, such as '€'
decimalSeparatorThe decimal separator
groupingSeparatorThe grouping (thousands) separator
usesMetricSystemWhether the metric system is used
calendarIdentifierThe calendar, such as 'gregorian'
collationIdentifierThe rules for sorting text
collatorIdentifierThe identifier used when sorting text
quotationBeginDelimiterThe opening quotation mark
quotationEndDelimiterThe closing quotation mark
alternateQuotationBeginDelimiterThe opening quotation mark for a quotation nested inside another
alternateQuotationEndDelimiterThe closing quotation mark for a quotation nested inside another

Instance methods ​

These give the name of a code in this locale's language:

MethodDescription
localizedStringForLocaleIdentifier()The name of a locale identifier: 'fr_FR' → 'French (France)'
localizedStringForLanguageCode()The name of a language: 'de' → 'German'
localizedStringForCountryCode()The name of a country or region: 'JP' → 'Japan'
localizedStringForScriptCode()The name of a script: 'Hant' → 'Traditional Han'
localizedStringForVariantCode()The name of a variant
localizedStringForCalendarIdentifier()The name of a calendar: 'gregorian' → 'Gregorian Calendar'
localizedStringForCollationIdentifier()The name of a collation
localizedStringForCurrencyCode()The name of a currency: 'EUR' → 'Euro'
localizedStringForCollatorIdentifier()The name of a collator identifier

Events ​

NSLocale fires no events of its own. When the user changes the region settings, the event that fires is localechange on application.

Examples ​

Reading the user's language and region ​

js
const locale = NSLocale.currentLocale;
console.log(JSON.stringify(NSLocale.preferredLanguages));
console.log(locale.languageCode, locale.regionCode, locale.currencyCode);
console.log(locale.decimalSeparator, locale.usesMetricSystem);

Result: running the acceptance app (which supports English only) on the iPhone Air simulator (iOS 27.2, system language Simplified Chinese, region China) prints three lines:

["zh-Hans-CN"]
en CN CNY
. true

The preferred language is Chinese, yet the language of currentLocale is English: the app supports only English, so the system gives it English.

Choosing the interface language ​

When the app ships text in several languages and needs to pick one by the user's preference, walk preferredLanguages in order and take the first one the app has:

js
const supported = ['en', 'zh-Hans', 'ja'];
function pickLanguage() {
  for (const tag of NSLocale.preferredLanguages) {
    const locale = new NSLocale(tag);
    const script = locale.scriptCode;
    const candidates = [script === null ? locale.languageCode : locale.languageCode + '-' + script, locale.languageCode];
    for (const c of candidates) {
      if (supported.includes(c)) return c;
    }
  }
  return supported[0];
}
console.log(pickLanguage());

Result: when the preferred language is zh-Hans-CN, the scriptCode of new NSLocale('zh-Hans-CN') is 'Hans', and the output is zh-Hans. Not verified in the simulator.

Corresponding iOS API ​

ObjCJS
[NSLocale preferredLanguages]NSLocale.preferredLanguages
[NSLocale currentLocale]NSLocale.currentLocale
[[NSLocale alloc] initWithLocaleIdentifier:@"de_DE"]new NSLocale('de_DE')
locale.regionCodelocale.regionCode
locale.countryCodelocale.regionCode
[locale objectForKey:NSLocaleCurrencyCode]locale.currencyCode
[locale displayNameForKey:NSLocaleLanguageCode value:@"de"]locale.localizedStringForLanguageCode('de')
NSLocaleLanguageDirectionRightToLeft'rightToLeft'
NSCurrentLocaleDidChangeNotificationapplication.addEventListener('localechange', …)

See also ​