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:
NSLocale.preferredLanguages: the languages the user has ordered in Settings.NSLocale.currentLocale: the locale the app uses. The language is the one the app actually uses, picked from the languages the app declares it supports; the country or region and the formats are what the user set in Settings.NSLocale.autoupdatingCurrentLocale: the same, but its values follow changes to the user's settings.
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
Creates a locale from a locale identifier, for example new NSLocale('de_DE').
Static properties
| Property | Description |
|---|---|
preferredLanguages read-only | The languages the user has ordered in Settings |
currentLocale read-only | The locale the app uses, as of the moment it is read |
autoupdatingCurrentLocale read-only | The locale the app uses, with values that follow the settings |
systemLocale read-only | A generic locale that belongs to no language or region |
availableLocaleIdentifiers read-only | Every locale identifier the system recognizes |
ISOLanguageCodes read-only | Every language code |
ISOCountryCodes read-only | Every country and region code |
ISOCurrencyCodes read-only | Every currency code |
commonISOCurrencyCodes read-only | Commonly used currency codes |
Static methods
| Method | Description |
|---|---|
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:
| Property | Description |
|---|---|
localeIdentifier | The locale identifier, such as 'de_DE' |
languageCode | The language code, such as 'de' |
languageIdentifier | The language identifier, such as 'de-DE' |
regionCode | The country or region code, such as 'DE'; may be null |
scriptCode | The script code, such as 'Hant'; may be null |
variantCode | The variant code; may be null |
Formats:
| Property | Description |
|---|---|
currencyCode | The currency code, such as 'EUR'; may be null |
currencySymbol | The currency symbol, such as '€' |
decimalSeparator | The decimal separator |
groupingSeparator | The grouping (thousands) separator |
usesMetricSystem | Whether the metric system is used |
calendarIdentifier | The calendar, such as 'gregorian' |
collationIdentifier | The rules for sorting text |
collatorIdentifier | The identifier used when sorting text |
quotationBeginDelimiter | The opening quotation mark |
quotationEndDelimiter | The closing quotation mark |
alternateQuotationBeginDelimiter | The opening quotation mark for a quotation nested inside another |
alternateQuotationEndDelimiter | The closing quotation mark for a quotation nested inside another |
Instance methods
These give the name of a code in this locale's language:
| Method | Description |
|---|---|
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
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
. trueThe 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:
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
| ObjC | JS |
|---|---|
[NSLocale preferredLanguages] | NSLocale.preferredLanguages |
[NSLocale currentLocale] | NSLocale.currentLocale |
[[NSLocale alloc] initWithLocaleIdentifier:@"de_DE"] | new NSLocale('de_DE') |
locale.regionCode | locale.regionCode |
locale.countryCode | locale.regionCode |
[locale objectForKey:NSLocaleCurrencyCode] | locale.currencyCode |
[locale displayNameForKey:NSLocaleLanguageCode value:@"de"] | locale.localizedStringForLanguageCode('de') |
NSLocaleLanguageDirectionRightToLeft | 'rightToLeft' |
NSCurrentLocaleDidChangeNotification | application.addEventListener('localechange', …) |
See also
Intl.NumberFormat,Intl.DateTimeFormat: write numbers and dates as text for a localelocalechange: the user changed the region settings- Configuring the app: name, languages, usage descriptions:
ios.languagesdeclares which languages the app supports application.layoutDirection: whether the interface runs left to right or right to left