React Native Localize Toolbox

Common errors

• TypeError: null is not an object (evaluating 'RNDeviceInfo.getConstants')

  cause The native module for `react-native-localize` (or its underlying dependencies) was not correctly linked or initialized with the React Native bridge.
  fix Ensure `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'] }

  cause 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.
  fix Add 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

  cause 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.
  fix For `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.

Warnings

• breaking Starting from version `3.5.1`, `@expo/config-plugins` was moved to a peer dependency. Projects using the Expo config plugin must explicitly install it to avoid build failures.
  Fix: Run `npm install @expo/config-plugins` or `yarn add @expo/config-plugins` in your project root.
• gotcha When using the Expo config plugin (introduced in `3.5.0`), ensure you explicitly define the `locales` property in your `app.json` or `app.config.js/ts`. This is crucial for Android 13+ and iOS to correctly display available app languages in system settings. Failure to do so might result in locales not being registered correctly at the OS level.
  Fix: Add the `locales` array (e.g., `['en', 'fr']`) to the `react-native-localize` plugin configuration in your Expo config. This can also be an object like `{ android: ['en'], ios: ['en', 'fr'] }`.
• gotcha The `localize` function for the Expo config plugin must be imported differently based on your Expo config file type. For `app.config.ts` (ESM), use `import localize from 'react-native-localize/expo';`. For `app.config.js` (CommonJS), use `const localize = require('react-native-localize/expo');`. Incorrect syntax will lead to import errors.
  Fix: Match the import statement to your `app.config.js` or `app.config.ts` file's module system (CommonJS for `.js`, ES Modules for `.ts`).
• gotcha Version `3.6.0` introduced official SSR support. While beneficial, applications that previously relied on client-side-only localization logic or custom server-side mocks should verify their setup to ensure compatibility and prevent unexpected behavior during server-side rendering.
  Fix: Review your SSR environment and ensure `react-native-localize` functions behave as expected on the server, leveraging the new SSR capabilities.

Install

• npm install react-native-localize npm
• yarn add react-native-localize yarn
• pnpm add react-native-localize pnpm

Imports

• getLocales
  wrong:

  import getLocales from 'react-native-localize';

  correct:

  import { getLocales, getCurrencies } 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
  wrong:

  const localize = require('react-native-localize');

  correct:

  import localize from 'react-native-localize/expo';

  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.

Quickstart

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>
  );
}