{"id":11780,"library":"react-native-localize","title":"React Native Localize Toolbox","description":"react-native-localize is a comprehensive toolkit designed to streamline localization within React Native applications, including robust support for Android, iOS, macOS, and Web platforms via react-native-web. The current stable version is 3.7.0. The library's release cadence closely follows React Native's own support policy, focusing on compatibility with the latest version and the two previous minor series. Key differentiators include its broad cross-platform compatibility, an official Expo config plugin (introduced in 3.5.0 and actively refined), and recent additions like server-side rendering (SSR) support in version 3.6.0. It provides essential utilities for accessing device locale information, currency symbols, and managing right-to-left (RTL) layouts, integrating seamlessly into existing React Native projects. The library ships with TypeScript types for enhanced developer experience.","status":"active","version":"3.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/zoontek/react-native-localize","tags":["javascript","react-native-localize","react-native","react-native-macos","localize","localization","l20n","typescript"],"install":[{"cmd":"npm install react-native-localize","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-localize","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-localize","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Essential for integrating with Expo's build system and enabling platform-specific localization settings through the config plugin.","package":"@expo/config-plugins","optional":true},{"reason":"The core UI library for all React Native applications.","package":"react","optional":false},{"reason":"The foundational framework for building native mobile applications with React.","package":"react-native","optional":false},{"reason":"Provides specific platform support for macOS applications using React Native.","package":"react-native-macos","optional":true}],"imports":[{"note":"Most utility functions (e.g., `getLocales`, `getCurrencies`, `findBestAvailableLanguage`) are named exports. Using a default import will result in `undefined` or errors.","wrong":"import getLocales from 'react-native-localize';","symbol":"getLocales","correct":"import { getLocales, getCurrencies } from 'react-native-localize';"},{"note":"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');`.","wrong":"const localize = require('react-native-localize');","symbol":"localize","correct":"import localize from 'react-native-localize/expo';"},{"note":"TypeScript types like `Locale` should be imported using `import type` for clarity and better tree-shaking, ensuring they are only used for type checking.","symbol":"Locale","correct":"import type { Locale } from 'react-native-localize';"}],"quickstart":{"code":"import React, { useEffect, useState } from 'react';\nimport { Text, View, StyleSheet, Platform } from 'react-native';\nimport {\n  getLocales,\n  getCurrencies,\n  getTimezone,\n  getCountry,\n  findBestAvailableLanguage,\n  isRTL,\n  addEventListener,\n  removeEventListener,\n  type Locale,\n} from 'react-native-localize';\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: '#F5FCFF',\n    padding: 20,\n  },\n  title: {\n    fontSize: 20,\n    textAlign: 'center',\n    margin: 10,\n  },\n  info: {\n    textAlign: 'center',\n    color: '#333333',\n    marginBottom: 5,\n  },\n});\n\nexport default function App() {\n  const [currentLocales, setCurrentLocales] = useState<Locale[]>(getLocales());\n\n  useEffect(() => {\n    const handleLocalesChange = () => {\n      setCurrentLocales(getLocales());\n    };\n    addEventListener('change', handleLocalesChange);\n    return () => removeEventListener('change', handleLocalesChange);\n  }, []);\n\n  const bestLanguage = findBestAvailableLanguage(['en', 'fr', 'es']);\n  const isCurrentLocaleRTL = isRTL();\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.title}>\n        React Native Localize Example\n      </Text>\n      <Text style={styles.info}>\n        Current Platform: {Platform.OS}\n      </Text>\n      <Text style={styles.info}>\n        Device Locales: {currentLocales.map(l => l.languageTag).join(', ')}\n      </Text>\n      <Text style={styles.info}>\n        Preferred Language (from ['en', 'fr', 'es']): {bestLanguage?.languageTag ?? 'N/A'}\n      </Text>\n      <Text style={styles.info}>\n        Device Country: {getCountry()}\n      </Text>\n      <Text style={styles.info}>\n        Device Currencies: {getCurrencies().join(', ')}\n      </Text>\n      <Text style={styles.info}>\n        Device Timezone: {getTimezone()}\n      </Text>\n      <Text style={styles.info}>\n        Is Right-to-Left (RTL): {isCurrentLocaleRTL ? 'Yes' : 'No'}\n      </Text>\n    </View>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Run `npm install @expo/config-plugins` or `yarn add @expo/config-plugins` in your project root.","message":"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.","severity":"breaking","affected_versions":">=3.5.1"},{"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'] }`.","message":"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.","severity":"gotcha","affected_versions":">=3.5.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=3.5.0"},{"fix":"Review your SSR environment and ensure `react-native-localize` functions behave as expected on the server, leveraging the new SSR capabilities.","message":"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.","severity":"gotcha","affected_versions":">=3.6.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"The native module for `react-native-localize` (or its underlying dependencies) was not correctly linked or initialized with the React Native bridge.","error":"TypeError: null is not an object (evaluating 'RNDeviceInfo.getConstants')"},{"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.","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.","error":"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'] }"},{"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.","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.","error":"SyntaxError: require() not supported in ES module scope"}],"ecosystem":"npm"}