HomeGuidesReferenceLearn
ArchiveExpo SnackDiscordForumsChangelogNewsletter

Expo Localization iconExpo Localization

GitHub

npm

A library that provides an interface for native user localization information.

expo-localization allows you to Localize your app, customizing the experience for specific regions, languages, or cultures. It also provides access to the locale data on the native device. Using a localization library such as lingui-js, react-intl or i18n-js with expo-localization will enable you to create a very accessible experience for users.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb

Installation

Terminal
- npx expo install expo-localization

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

Find more information about using expo-localization in the Localization guide.

API

import { getLocales, getCalendars } from 'expo-localization';

Behavior

You can use synchronous getLocales() and getCalendars() methods to get the locale settings of the user device. On iOS, the results will remain the same while the app is running.

On Android, the user can change locale preferences in Settings without restarting apps. To keep the localization current, you can rerun the getLocales() and getCalendars() methods every time the app returns to the foreground. Use AppState to detect this.

Constants

Deprecated. Use Localization.getLocales() instead. Three-character ISO 4217 currency code. Returns null on web.

Localization.currency

Type: null | string


Example

'USD', 'EUR', 'CNY', null

Deprecated. Use Localization.getLocales() instead. Decimal separator used for formatting numbers.

Localization.decimalSeparator

Type: string


Example

',', '.'

Deprecated. Use Localization.getLocales() instead. Digit grouping separator used when formatting numbers larger than 1000.

Localization.digitGroupingSeparator

Type: string


Example

'.', '', ','

Deprecated. Use Localization.getLocales() instead. Boolean value that indicates whether the system uses the metric system. On Android and web, this is inferred from the current region.

Localization.isMetric

Type: boolean


Deprecated. Use Localization.getLocales() instead. Returns if the system's language is written from Right-to-Left. This can be used to build features like bidirectional icons.

Returns false in Server Side Rendering (SSR) environments.

Localization.isRTL

Type: boolean


Deprecated. Use Localization.getLocales() instead. A list of all the supported language ISO codes.

Localization.isoCurrencyCodes

Type: string[]


Localization.locale

Type: string


Consider using Localization.getLocales() for a list of user preferred locales instead. An IETF BCP 47 language tag, consisting of a two-character language code and optional script, region and variant codes.

Example

'en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng'

Deprecated. Use Localization.getLocales() instead. List of all the native languages provided by the user settings. These are returned in the order the user defines in their device settings.

Localization.locales

Type: string[]


Example

['en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng']

Deprecated. Use Localization.getLocales() instead. The region code for your device that comes from the Region setting under Language & Region on iOS. This value is always available on iOS, but might return null on Android or web.

Localization.region

Type: null | string


Example

'US', 'NZ', null

Deprecated. Use Localization.getLocales() instead. The current time zone in display format. On Web time zone is calculated with Intl.DateTimeFormat().resolvedOptions().timeZone. For a better estimation you could use the moment-timezone package but it will add significant bloat to your website's bundle size.

Localization.timezone

Type: string


Example

'America/Los_Angeles'

Hooks

useCalendars()

A hook providing a list of user's preferred calendars, returned as an array of objects of type Calendar. Guaranteed to contain at least 1 element. For now always returns a single element, but it's likely to return a user preference list on some platforms in the future. If the OS settings change, the hook will rerender with a new list of calendars.

Example

[ { "calendar": "gregory", "timeZone": "Europe/Warsaw", "uses24hourClock": true, "firstWeekday": 1 } ]

Returns

  • Calendar[]

useLocales()

A hook providing a list of user's locales, returned as an array of objects of type Locale. Guaranteed to contain at least 1 element. These are returned in the order the user defines in their device settings. On the web currency and measurements systems are not provided, instead returned as null. If needed, you can infer them from the current region using a lookup table. If the OS settings change, the hook will rerender with a new list of locales.

Example

[{ "languageTag": "pl-PL", "languageCode": "pl", "textDirection": "ltr", "digitGroupingSeparator": " ", "decimalSeparator": ",", "measurementSystem": "metric", "currencyCode": "PLN", "currencySymbol": "zł", "regionCode": "PL" }]

Returns


Methods

Localization.getCalendars()

List of user's preferred calendars, returned as an array of objects of type Calendar. Guaranteed to contain at least 1 element. For now always returns a single element, but it's likely to return a user preference list on some platforms in the future.

Example

[ { "calendar": "gregory", "timeZone": "Europe/Warsaw", "uses24hourClock": true, "firstWeekday": 1 } ]

Returns


Localization.getLocales()

List of user's locales, returned as an array of objects of type Locale. Guaranteed to contain at least 1 element. These are returned in the order the user defines in their device settings. On the web currency and measurements systems are not provided, instead returned as null. If needed, you can infer them from the current region using a lookup table.

Example

[{ "languageTag": "pl-PL", "languageCode": "pl", "textDirection": "ltr", "digitGroupingSeparator": " ", "decimalSeparator": ",", "measurementSystem": "metric", "currencyCode": "PLN", "currencySymbol": "zł", "regionCode": "PL" }]

Returns


Deprecated. Use Localization.getLocales() or Localization.getCalendars() instead.

Localization.getLocalizationAsync()

Get the latest native values from the device. Locale can be changed on some Android devices without resetting the app.

On iOS, changing the locale will cause the device to reset meaning the constants will always be correct.

Example

// When the app returns from the background on Android...

const { locale } = await Localization.getLocalizationAsync();

Returns


Types

Calendar

NameTypeDescription
calendarCalendarIdentifier | null

The calendar identifier, one of Unicode calendar types.

On Android is limited to one of device's available calendar types.

On iOS uses calendar identifiers, but maps them to the corresponding Unicode types, will also never contain 'dangi' or 'islamic-rgsa' due to it not being implemented on iOS.

firstWeekdayWeekday | null

The first day of the week. For most calendars Sunday is numbered 1, with Saturday being number 7. Can be null on some browsers that don't support the weekInfo property in Intl API.

Example

1, 7.

timeZonestring | null

Time zone for the calendar. Can be null on Web.

Example

'America/Los_Angeles', 'Europe/Warsaw', 'GMT+1'.

uses24hourClockboolean | null

True when current device settings use 24 hour time format. Can be null on some browsers that don't support the hourCycle property in Intl API.

Locale

NameTypeDescription
currencyCodestring | null

Currency code for the locale. Is null on Web, use a table lookup based on region instead.

Example

'USD', 'EUR', 'PLN'.

currencySymbolstring | null

Currency symbol for the locale. Is null on Web, use a table lookup based on region (if available) instead.

Example

'$', '€', 'zł'.

decimalSeparatorstring | null

Decimal separator used for formatting numbers with fractional parts.

Example

'.', ','.

digitGroupingSeparatorstring | null

Digit grouping separator used for formatting large numbers.

Example

'.', ','.

languageCodestring

An IETF BCP 47 language tag without the region code.

Example

'en', 'es', 'pl'.

languageTagstring

An IETF BCP 47 language tag with a region code.

Example

'en-US', 'es-419', 'pl-PL'.

measurementSystem'metric' | 'us' | 'uk' | null

The measurement system used in the locale. Is null on Web, as user chosen measurement system is not exposed on the web and using locale to determine measurement systems is unreliable. Ask for user preferences if possible.

regionCodestring | null

The region code for your device that comes from the Region setting under Language & Region on iOS, Region settings on Android and is parsed from locale on Web (can be null on Web).

textDirection'ltr' | 'rtl' | null

Text direction for the locale. One of: 'ltr', 'rtl', but can also be null on some browsers without support for the textInfo property in Intl API.

Localization

NameTypeDescription
currencystring | null

Three-character ISO 4217 currency code. Returns null on web.

Example

'USD', 'EUR', 'CNY', null

decimalSeparatorstring

Decimal separator used for formatting numbers.

Example

',', '.'

digitGroupingSeparatorstring

Digit grouping separator used when formatting numbers larger than 1000.

Example

'.', '', ','

isMetricboolean

Boolean value that indicates whether the system uses the metric system. On Android and web, this is inferred from the current region.

isRTLboolean

Returns if the system's language is written from Right-to-Left. This can be used to build features like bidirectional icons.

Returns false in Server Side Rendering (SSR) environments.

isoCurrencyCodesstring[]

A list of all the supported language ISO codes.

localestring

An IETF BCP 47 language tag, consisting of a two-character language code and optional script, region and variant codes.

Example

'en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng'

localesstring[]

List of all the native languages provided by the user settings. These are returned in the order that the user defined in the device settings.

Example

['en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng']

regionstring | null

The region code for your device that comes from the Region setting under Language & Region on iOS. This value is always available on iOS, but might return null on Android or web.

Example

'US', 'NZ', null

timezonestring

The current time zone in display format. On Web time zone is calculated with Intl.DateTimeFormat().resolvedOptions().timeZone. For a better estimation you could use the moment-timezone package but it will add significant bloat to your website's bundle size.

Example

'America/Los_Angeles'

Enums

CalendarIdentifier

The calendar identifier, one of Unicode calendar types. Gregorian calendar is aliased and can be referred to as both CalendarIdentifier.GREGORIAN and CalendarIdentifier.GREGORY.

BUDDHIST

CalendarIdentifier.BUDDHIST ＝ "buddhist"

Thai Buddhist calendar

CHINESE

CalendarIdentifier.CHINESE ＝ "chinese"

Traditional Chinese calendar

COPTIC

CalendarIdentifier.COPTIC ＝ "coptic"

Coptic calendar

DANGI

CalendarIdentifier.DANGI ＝ "dangi"

Traditional Korean calendar

ETHIOAA

CalendarIdentifier.ETHIOAA ＝ "ethioaa"

Ethiopic calendar, Amete Alem (epoch approx. 5493 B.C.E)

ETHIOPIC

CalendarIdentifier.ETHIOPIC ＝ "ethiopic"

Ethiopic calendar, Amete Mihret (epoch approx, 8 C.E.)

GREGORIAN

CalendarIdentifier.GREGORIAN ＝ "gregory"

Gregorian calendar (alias)

GREGORY

CalendarIdentifier.GREGORY ＝ "gregory"

Gregorian calendar

HEBREW

CalendarIdentifier.HEBREW ＝ "hebrew"

Traditional Hebrew calendar

INDIAN

CalendarIdentifier.INDIAN ＝ "indian"

Indian calendar

ISLAMIC

CalendarIdentifier.ISLAMIC ＝ "islamic"

Islamic calendar

ISLAMIC_CIVIL

CalendarIdentifier.ISLAMIC_CIVIL ＝ "islamic-civil"

Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - civil epoch)

ISLAMIC_RGSA

CalendarIdentifier.ISLAMIC_RGSA ＝ "islamic-rgsa"

Islamic calendar, Saudi Arabia sighting

ISLAMIC_TBLA

CalendarIdentifier.ISLAMIC_TBLA ＝ "islamic-tbla"

Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - astronomical epoch)

ISLAMIC_UMALQURA

CalendarIdentifier.ISLAMIC_UMALQURA ＝ "islamic-umalqura"

Islamic calendar, Umm al-Qura

ISO8601

CalendarIdentifier.ISO8601 ＝ "iso8601"

ISO calendar (Gregorian calendar using the ISO 8601 calendar week rules)

JAPANESE

CalendarIdentifier.JAPANESE ＝ "japanese"

Japanese imperial calendar

PERSIAN

CalendarIdentifier.PERSIAN ＝ "persian"

Persian calendar

ROC

CalendarIdentifier.ROC ＝ "roc"

Civil (algorithmic) Arabic calendar

Weekday

An enum mapping days of the week in Gregorian calendar to their index as returned by the firstWeekday property.

SUNDAY

Weekday.SUNDAY ＝ 1

MONDAY

Weekday.MONDAY ＝ 2

TUESDAY

Weekday.TUESDAY ＝ 3

WEDNESDAY

Weekday.WEDNESDAY ＝ 4

THURSDAY

Weekday.THURSDAY ＝ 5

FRIDAY

Weekday.FRIDAY ＝ 6

SATURDAY

Weekday.SATURDAY ＝ 7