This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Localization
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-i18next, react-intl, i18n-js or react-native-intlayer with expo-localization will enable you to create a very accessible experience for users.
Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
Configuration in app config
You can configure expo-localization using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.
Example app.json with config plugin
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.
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, ...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.
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, ...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.
Example
[{ "languageTag": "pl-PL", "languageCode": "pl", "textDirection": "ltr", "digitGroupingSeparator": " ", "decimalSeparator": ",", "measurementSystem": "metric", "currencyCode": "PLN", "currencySymbol": "zł", "regionCode": "PL", "temperatureUnit": "celsius" }]
Types
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.