What is react-native-localize?
The react-native-localize package provides localization utilities for React Native applications. It helps in handling various localization tasks such as determining the user's locale, timezone, and country, as well as formatting numbers, dates, and times according to the user's locale.
What are react-native-localize's main functionalities?
Get User's Locale
This feature allows you to get the list of locales preferred by the user. The code sample retrieves the user's preferred locales and logs them to the console.
const { getLocales } = require('react-native-localize');
const locales = getLocales();
console.log(locales);
Get User's Timezone
This feature allows you to get the user's current timezone. The code sample retrieves the user's timezone and logs it to the console.
const { getTimeZone } = require('react-native-localize');
const timeZone = getTimeZone();
console.log(timeZone);
Get User's Country
This feature allows you to get the user's current country. The code sample retrieves the user's country and logs it to the console.
const { getCountry } = require('react-native-localize');
const country = getCountry();
console.log(country);
Format Number
This feature allows you to get the number formatting settings for the user's locale. The code sample retrieves the decimal and grouping separators and logs them to the console.
const { getNumberFormatSettings } = require('react-native-localize');
const { decimalSeparator, groupingSeparator } = getNumberFormatSettings();
console.log(`Decimal Separator: ${decimalSeparator}, Grouping Separator: ${groupingSeparator}`);
Handle Localization Changes
This feature allows you to handle changes in localization settings. The code sample adds an event listener that logs a message when localization settings change.
const { addEventListener, removeEventListener } = require('react-native-localize');
const handleLocalizationChange = () => {
console.log('Localization settings changed');
};
addEventListener('change', handleLocalizationChange);
// To remove the listener
// removeEventListener('change', handleLocalizationChange);
Other packages similar to react-native-localize
i18next
i18next is a popular internationalization framework for JavaScript that provides a complete solution for localizing your app. It supports multiple languages, pluralization, and interpolation. Compared to react-native-localize, i18next offers more comprehensive internationalization features but requires more setup.
react-intl
react-intl is a library for internationalizing React applications. It provides components and an API to format dates, numbers, and strings, and to handle pluralization. While react-intl focuses on formatting and message handling, react-native-localize provides more utilities for determining the user's locale and timezone.
expo-localization
expo-localization is a package from the Expo ecosystem that provides localization utilities similar to react-native-localize. It can determine the user's locale, timezone, and country. However, expo-localization is designed to work seamlessly with Expo projects, whereas react-native-localize can be used in any React Native project.
🌍 react-native-localize
A toolbox for your React Native app localization.

Support
This library follows the React Native releases support policy.
It is supporting the latest version, and the two previous minor series.
Setup
$ npm install --save react-native-localize
$ yarn add react-native-localize
Don't forget to run pod install
after that !
Web support
This package supports react-native-web
. Follow their official guide to configure webpack
.
Debugging
As this library uses synchronous native methods, remote debugging (e.g. with Chrome) is no longer possible.
Instead, you should use Flipper 🐬.
Basic usage example
import { getCurrencies, getLocales } from "react-native-localize";
console.log(getLocales());
console.log(getCurrencies());
API
getLocales()
Returns the user preferred locales, in order.
Method type
type getLocales = () => Array<{
languageCode: string;
scriptCode?: string;
countryCode: string;
languageTag: string;
isRTL: boolean;
}>;
Usage example
import { getLocales } from "react-native-localize";
console.log(getLocales());
getNumberFormatSettings()
Returns number formatting settings.
Method type
type getNumberFormatSettings = () => {
decimalSeparator: string;
groupingSeparator: string;
};
Usage example
import { getNumberFormatSettings } from "react-native-localize";
console.log(getNumberFormatSettings());
getCurrencies()
Returns the user preferred currency codes, in order.
Method type
type getCurrencies = () => string[];
Usage example
import { getCurrencies } from "react-native-localize";
console.log(getCurrencies());
getCountry()
Returns the user current country code (based on its device locale, not on its position).
Method type
type getCountry = () => string;
Usage example
import { getCountry } from "react-native-localize";
console.log(getCountry());
Note
Devices using Latin American regional settings will return "UN" instead of "419", as the latter is not a standard country code.
getCalendar()
Returns the user preferred calendar format.
Method type
type getCalendar = () =>
| "gregorian"
| "buddhist"
| "coptic"
| "ethiopic"
| "ethiopic-amete-alem"
| "hebrew"
| "indian"
| "islamic"
| "islamic-umm-al-qura"
| "islamic-civil"
| "islamic-tabular"
| "iso8601"
| "japanese"
| "persian";
Usage example
import { getCalendar } from "react-native-localize";
console.log(getCalendar());
getTemperatureUnit()
Returns the user preferred temperature unit.
Method type
type getTemperatureUnit = () => "celsius" | "fahrenheit";
Usage example
import { getTemperatureUnit } from "react-native-localize";
console.log(getTemperatureUnit());
getTimeZone()
Returns the user preferred timezone (based on its device settings, not on its position).
Method type
type getTimeZone = () => string;
Usage example
import { getTimeZone } from "react-native-localize";
console.log(getTimeZone());
uses24HourClock()
Returns true
if the user prefers 24h clock format, false
if they prefer 12h clock format.
Method type
type uses24HourClock = () => boolean;
Usage example
import { uses24HourClock } from "react-native-localize";
console.log(uses24HourClock());
usesMetricSystem()
Returns true
if the user prefers metric measure system, false
if they prefer imperial.
Method type
type usesMetricSystem = () => boolean;
Usage example
import { usesMetricSystem } from "react-native-localize";
console.log(usesMetricSystem());
usesAutoDateAndTime()
Tells if the automatic date & time setting is enabled on the phone. Android only
Method type
type usesAutoDateAndTime = () => boolean | undefined;
Usage example
import { usesAutoDateAndTime } from "react-native-localize";
console.log(usesAutoDateAndTime());
usesAutoTimeZone()
Tells if the automatic time zone setting is enabled on the phone. Android only
Method type
type usesAutoTimeZone = () => boolean | undefined;
Usage example
import { usesAutoTimeZone } from "react-native-localize";
console.log(usesAutoTimeZone());
findBestLanguageTag()
Returns the best language tag possible and its reading direction. Useful to pick the best translation available.
[!NOTE]
It respects the user preferred languages list order (see explanations).
Method type
type findBestLanguageTag = (
languageTags: string[],
) => { languageTag: string; isRTL: boolean } | void;
Usage example
import { findBestLanguageTag } from "react-native-localize";
console.log(findBestLanguageTag(["en-US", "en", "fr"]));
openAppLanguageSettings()
Opens the app language settings.
[!WARNING]
This feature is available only on Android 13+ and require configuring your app's supported locales.
Method type
type openAppLanguageSettings = () => Promise<void>;
Usage example
import { openAppLanguageSettings } from "react-native-localize";
openAppLanguageSettings("application").catch((error) => {
console.warn("Cannot open app language settings", error);
});
Browse the files in the /example directory.
How to update supported localizations (iOS)
You can add / remove supported localizations in your Xcode project infos:

How to test your code
Because it's a native module, you need to mock this package.
The package provides a default mock you may import in your __mocks__
directory:
export * from "react-native-localize/mock";
This module is provided as is, I work on it in my free time.
If you or your company uses it in a production app, consider sponsoring this project 💰. You also can contact me for premium enterprise support: help with issues, prioritize bugfixes, feature requests, etc.
