This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 52).
Expo LocalizationA 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-i18next, react-intl or i18n-js with expo-localization will enable you to create a very accessible experience for users.
Installation
- npx expo install expo-localizationIf you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
Configuration in app.json/app.config.js
You can configure expo-localization using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
Example app.json with config plugin
{
"expo": {
"plugins": ["expo-localization"]
}
}
Usage
Find more information about using expo-localization and adding support for right-to-left languages 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. An IETF BCP 47 language tag, consisting of a two-character language code and optional script, region and variant codes.
Type: string
Example
'en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng'
Hooks
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.
Calendar[]Example
[{
"calendar": "gregory",
"timeZone": "Europe/Warsaw",
"uses24hourClock": true,
"firstWeekday": 1
}]
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.
Locale[]Example
[{
"languageTag": "pl-PL",
"languageCode": "pl",
"textDirection": "ltr",
"digitGroupingSeparator": " ",
"decimalSeparator": ",",
"measurementSystem": "metric",
"currencyCode": "PLN",
"currencySymbol": "zł",
"regionCode": "PL",
"temperatureUnit": "celsius"
}]
Methods
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.
Calendar[]Example
[{
"calendar": "gregory",
"timeZone": "Europe/Warsaw",
"uses24hourClock": true,
"firstWeekday": 1
}]
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.
Locale[]Example
[{
"languageTag": "pl-PL",
"languageCode": "pl",
"textDirection": "ltr",
"digitGroupingSeparator": " ",
"decimalSeparator": ",",
"measurementSystem": "metric",
"currencyCode": "PLN",
"currencySymbol": "zł",
"regionCode": "PL",
"temperatureUnit": "celsius"
}]
Types
| Property | Type | Description |
|---|---|---|
| calendar | CalendarIdentifier | 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 |
| firstWeekday | Weekday | null | |
| timeZone | string | null | Time zone for the calendar. Can be Example
|
| uses24hourClock | boolean | null |
| Property | Type | Description |
|---|---|---|
| currencyCode | string | null | Currency code for the locale.
On iOS, it's the currency code from the Example
|
| currencySymbol | string | null | Currency symbol for the currency specified by Example
|
| decimalSeparator | string | null | Decimal separator used for formatting numbers with fractional parts. Example
|
| digitGroupingSeparator | string | null | Digit grouping separator used for formatting large numbers. Example
|
| langageCurrencyCode | string | null | Currency code for the locale.
On iOS, it's the currency code for the current locale in the list, not the device region.
On Android, it's equal to Example
|
| langageCurrencySymbol | string | null | Currency symbol for the currency specified by Example
|
| languageCode | string | null | An IETF BCP 47 language tag without the region code. Example
|
| languageRegionCode | string | null | The region code for the preferred language. When the language is not region-specific, it returns the same value as Example
|
| languageTag | string | An IETF BCP 47 language tag with a region code. Example
|
| measurementSystem | 'metric' | 'us' | 'uk' | null | The measurement system used in the locale.
Is |
| regionCode | string | 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 Example
|
| temperatureUnit | 'celsius' | 'fahrenheit' | null | The temperature unit used in the locale.
Returns |
| textDirection | 'ltr' | 'rtl' | null |
| Property | Type | Description |
|---|---|---|
| currency | string | null | Three-character ISO 4217 currency code. Returns Example
|
| decimalSeparator | string | Decimal separator used for formatting numbers. Example
|
| digitGroupingSeparator | string | Digit grouping separator used when formatting numbers larger than 1000. Example
|
| isMetric | boolean | Boolean value that indicates whether the system uses the metric system. On Android and web, this is inferred from the current region. |
| isoCurrencyCodes | string[] | A list of all the supported language ISO codes. |
| isRTL | boolean | Returns if the system's language is written from Right-to-Left. This can be used to build features like bidirectional icons. Returns |
| locale | string | An IETF BCP 47 language tag, consisting of a two-character language code and optional script, region and variant codes. Example
|
| locales | string[] | 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
|
| region | string | 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 Example
|
| timezone | string | 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
|
Enums
The calendar identifier, one of Unicode calendar types.
Gregorian calendar is aliased and can be referred to as both CalendarIdentifier.GREGORIAN and CalendarIdentifier.GREGORY.
CalendarIdentifier.ETHIOAA ＝ "ethioaa"Ethiopic calendar, Amete Alem (epoch approx. 5493 B.C.E)
CalendarIdentifier.ETHIOPIC ＝ "ethiopic"Ethiopic calendar, Amete Mihret (epoch approx, 8 C.E.)
CalendarIdentifier.ISLAMIC_CIVIL ＝ "islamic-civil"Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - civil epoch)
CalendarIdentifier.ISLAMIC_TBLA ＝ "islamic-tbla"Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - astronomical epoch)
CalendarIdentifier.ISLAMIC_UMALQURA ＝ "islamic-umalqura"Islamic calendar, Umm al-Qura
CalendarIdentifier.ISO8601 ＝ "iso8601"ISO calendar (Gregorian calendar using the ISO 8601 calendar week rules)
An enum mapping days of the week in Gregorian calendar to their index as returned by the firstWeekday property.