Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
getLocales
✓ import { getLocales, getCurrencies } from 'react-native-localize';
✗ import getLocales from 'react-native-localize';
Most utility functions (e.g., `getLocales`, `getCurrencies`, `findBestAvailableLanguage`) are named exports. Using a default import will result in `undefined` or errors.
localize
✓ import localize from 'react-native-localize/expo';
✗ const localize = require('react-native-localize');
This specific import path is for the Expo config plugin. In `app.config.ts` (ESM), use `import localize from 'react-native-localize/expo';`. In `app.config.js` (CommonJS), use `const localize = require('react-native-localize/expo');`.
Locale
✓ import type { Locale } from 'react-native-localize';
TypeScript types like `Locale` should be imported using `import type` for clarity and better tree-shaking, ensuring they are only used for type checking.
This example demonstrates how to fetch and display various localization information from the device, including current locales, best available language, country, currencies, timezone, and RTL status, with a listener for locale changes. This is a runnable React Native component.
import React, { useEffect, useState } from 'react';
import { Text, View, StyleSheet, Platform } from 'react-native';
import {
getLocales,
getCurrencies,
getTimezone,
getCountry,
findBestAvailableLanguage,
isRTL,
addEventListener,
removeEventListener,
type Locale,
} from 'react-native-localize';
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#F5FCFF',
padding: 20,
},
title: {
fontSize: 20,
textAlign: 'center',
margin: 10,
},
info: {
textAlign: 'center',
color: '#333333',
marginBottom: 5,
},
});
export default function App() {
const [currentLocales, setCurrentLocales] = useState<Locale[]>(getLocales());
useEffect(() => {
const handleLocalesChange = () => {
setCurrentLocales(getLocales());
};
addEventListener('change', handleLocalesChange);
return () => removeEventListener('change', handleLocalesChange);
}, []);
const bestLanguage = findBestAvailableLanguage(['en', 'fr', 'es']);
const isCurrentLocaleRTL = isRTL();
return (
<View style={styles.container}>
<Text style={styles.title}>
React Native Localize Example
</Text>
<Text style={styles.info}>
Current Platform: {Platform.OS}
</Text>
<Text style={styles.info}>
Device Locales: {currentLocales.map(l => l.languageTag).join(', ')}
</Text>
<Text style={styles.info}>
Preferred Language (from ['en', 'fr', 'es']): {bestLanguage?.languageTag ?? 'N/A'}
</Text>
<Text style={styles.info}>
Device Country: {getCountry()}
</Text>
<Text style={styles.info}>
Device Currencies: {getCurrencies().join(', ')}
</Text>
<Text style={styles.info}>
Device Timezone: {getTimezone()}
</Text>
<Text style={styles.info}>
Is Right-to-Left (RTL): {isCurrentLocaleRTL ? 'Yes' : 'No'}
</Text>
</View>
);
}
Errors
Common errors & fixes
TypeError: null is not an object (evaluating 'RNDeviceInfo.getConstants')
The native module for `react-native-localize` (or its underlying dependencies) was not correctly linked or initialized with the React Native bridge.
fixEnsure `pod install` has been run in your `ios` directory for iOS. For both platforms, verify that auto-linking is working correctly or manually link the module if necessary (though auto-linking is standard for modern React Native projects).
Error: [react-native-localize/expo] The 'locales' property is missing or invalid. Please provide an array of locale tags, e.g., ['en', 'fr'] or an object { android: ['en'], ios: ['fr'] }
The `locales` property within the `react-native-localize` Expo config plugin is either not provided or is in an incorrect format in your Expo configuration.
fixAdd or correct the `locales` property in your `app.json` or `app.config.js/ts` file, ensuring it's an array of locale strings or an object with `android` and `ios` arrays.
SyntaxError: require() not supported in ES module scope
Attempting to use `require()` for the Expo config plugin (`react-native-localize/expo`) in an `app.config.ts` file, which is interpreted as an ES module.
fixFor `app.config.ts` files, switch to ES module `import` syntax: `import localize from 'react-native-localize/expo';`. The `require` syntax is only for `app.config.js` files using CommonJS.
Audit
Dependencies
@expo/config-pluginsoptionalEssential for integrating with Expo's build system and enabling platform-specific localization settings through the config plugin.
reactrequiredThe core UI library for all React Native applications.
react-nativerequiredThe foundational framework for building native mobile applications with React.
react-native-macosoptionalProvides specific platform support for macOS applications using React Native.