expo-localization

Open Beta Documentation Amazon offers this technical documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback and iterates on the features. For the most current feature information, see the Release Notes.

@amazon-devices/expo-localization provides an interface for native user localization information.

It provdes getCalendars() and getLocales() method and their corresponding hooks, which return specific information about user's locale settings, for example languageCode, uses24HourClock, currencyCode and textDirection. It itself doesn't provide any methods for formatting text or values. Hooks will trigger a re-render when the app locale changes.

This is a system-deployed library and is available to React Native for Vega apps without a separate installation process. It is deployed as an autolinking library which your app links to at runtime. Compatibility is guaranteed only between the library and the version of React Native for Vega for which it is built.

Installation
Examples
API reference
- Constants
- Hooks
- Methods
Implementation details
Supported versions
Additional resources

Installation

Add the JavaScript library dependency in the package.json file.

Copied to clipboard.

 "dependencies": {
 ...
 "@amazon-devices/expo-localization": "~2.0.0",
 "@amazon-devices/keplerscript-turbomodule-api": "~1.0.0",
 ...
 }

Reinstall dependencies using npm install command.

Examples

The example below demonstrates how to retrieve a user's language code.

Copied to clipboard.

import React from 'react';
import {StyleSheet, Text, View} from 'react-native';
import {useLocales, useCalendars} from '@amazon-devices/expo-localization';

export const App = () => {
  const locales = useLocales();
  const calendars = useCalendars();

  return (
    <View style={styles.container}>
      <Text style={styles.text}>useLocales():</Text>
      <Text style={styles.text}>{JSON.stringify(locales, null, 2)}</Text>
      <Text style={styles.text}>useCalendars():</Text>
      <Text style={styles.text}>{JSON.stringify(calendars, null, 2)}</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    flexDirection: 'row',
    backgroundColor: 'white',
  },
  text: {
    color: 'black',
    fontSize: 32,
  },
});

API reference

Check out the dedicated documentation page for info about this library, API reference and more: Official Expo documentation for expo-localization.

Constants

Constant	Description
`locale`	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

Hooks

Hook Description

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

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

Hook	Description
`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
`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

Methods

Method	Description
`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
`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

Implementation details

The region field on Localization type is always null on Vega.
Functions useLocales(), useCalendars(), getCalendars() and getLocales() will always return array with one item in it, while other platforms could return empty array or multiple valid locales/calendars.
The deprecated constants and method: getLocalizationAsync() aren't supported on Vega

Supported versions

Package Version	Based On	@amazon-devices/react-native-kepler version
2.0.x	14.6.0	2.0.x

Additional resources

For information on additional libraries, see Supported Third-Party Libraries and Services.

Last updated: Sep 30, 2025