🌍 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
# --- or ---
$ yarn add react-native-localize

Don't forget to run pod install after that !

Expo plugin

If you're using Expo, you can specify the supported locales in your app.json or app.config.js using the config plugin. This enables Android 13+ and iOS to display the available locales in the system settings, allowing users to select their preferred language for your app.

{
"expo": {
"plugins": [["react-native-localize", { "locales": ["en", "fr"] }]]
}
}

Alternatively, if you want to define different locales for iOS and Android, you can use:

{
"expo": {
"plugins": [
[
"react-native-localize",
{
"locales": {
"android": ["en"],
"ios": ["en", "fr"]
}
}
]
]
}
}

Web support

This package supports react-native-web. Follow their official guide to configure webpack.

Basic usage example

import{getCurrencies,getLocales}from"react-native-localize";console.log(getLocales());console.log(getCurrencies());

Add smart, AI-powered translations to your app

Prismy (a proud sponsor of this library ♥️) helps teams ship localized apps faster with an AI-driven, GitHub-native workflow. Want to supercharge your react-native-localize setup? Here's how Prismy makes localization seamless:

🚀 Smart translations with zero fuss

• Customize tone (formal, informal, playful) per language.
• Automatically reuse existing translations.
• Use glossaries to keep terminology consistent (Prismy even generates them the initial one for you!)

No setup headaches. Just clean, context-aware translations, out of the box.

🔁 Continuous localization, built for developers

1. Keep editing your source locale files like you always do.
2. When you open a PR, Prismy:
   • Detects missing translations
   • (Optionally) adds a "Missing Translations" CI check
   • Comments with a link to generate them in one click
3. Kick off translations from the PR comment itself.
4. Let PMs, designers, or translators tweak the wording via Prismy's web UI.

👉 Learn more at prismy.io

API

getLocales()

Returns the user preferred locales, in order.

Method type

typegetLocales=()=>Array<{languageCode: string;scriptCode?: string;countryCode: string;languageTag: string;isRTL: boolean;}>;

Usage example

import{getLocales}from"react-native-localize";console.log(getLocales());/* -> [ { countryCode: "GB", languageTag: "en-GB", languageCode: "en", isRTL: false }, { countryCode: "US", languageTag: "en-US", languageCode: "en", isRTL: false }, { countryCode: "FR", languageTag: "fr-FR", languageCode: "fr", isRTL: false },] */

---

getNumberFormatSettings()

Returns number formatting settings.

Method type

typegetNumberFormatSettings=()=>{decimalSeparator: string;groupingSeparator: string;};

Usage example

import{getNumberFormatSettings}from"react-native-localize";console.log(getNumberFormatSettings());/* -> { decimalSeparator: ".", groupingSeparator: ",",} */

---

getCurrencies()

Returns the user preferred currency codes, in order.

Method type

typegetCurrencies=()=>string[];

Usage example

import{getCurrencies}from"react-native-localize";console.log(getCurrencies());// -> ["EUR", "GBP", "USD"]

---

getCountry()

Returns the user current country code (based on its device locale, not on its position).

Method type

typegetCountry=()=>string;

Usage example

import{getCountry}from"react-native-localize";console.log(getCountry());// -> "FR"

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

typegetCalendar=()=>|"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());// -> "gregorian"

---

getTemperatureUnit()

Returns the user preferred temperature unit.

Method type

typegetTemperatureUnit=()=>"celsius"|"fahrenheit";

Usage example

import{getTemperatureUnit}from"react-native-localize";console.log(getTemperatureUnit());// -> "celsius"

---

getTimeZone()

Returns the user preferred timezone (based on its device settings, not on its position).

Method type

typegetTimeZone=()=>string;

Usage example

import{getTimeZone}from"react-native-localize";console.log(getTimeZone());// -> "Europe/Paris"

---

uses24HourClock()

Returns true if the user prefers 24h clock format, false if they prefer 12h clock format.

Method type

typeuses24HourClock=()=>boolean;

Usage example

import{uses24HourClock}from"react-native-localize";console.log(uses24HourClock());// -> true

---

usesMetricSystem()

Returns true if the user prefers metric measure system, false if they prefer imperial.

Method type

typeusesMetricSystem=()=>boolean;

Usage example

import{usesMetricSystem}from"react-native-localize";console.log(usesMetricSystem());// -> true

---

usesAutoDateAndTime()

Tells if the automatic date & time setting is enabled on the phone. Android only

Method type

typeusesAutoDateAndTime=()=>boolean|undefined;

Usage example

import{usesAutoDateAndTime}from"react-native-localize";console.log(usesAutoDateAndTime());// true or false

---

usesAutoTimeZone()

Tells if the automatic time zone setting is enabled on the phone. Android only

Method type

typeusesAutoTimeZone=()=>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

typefindBestLanguageTag=(languageTags: string[],)=>{languageTag: string;isRTL: boolean}|void;

Usage example

import{findBestLanguageTag}from"react-native-localize";console.log(findBestLanguageTag(["en-US","en","fr"]));// -> { languageTag: "en-US", isRTL: false }

---

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

typeopenAppLanguageSettings=()=>Promise<void>;

Usage example

import{openAppLanguageSettings}from"react-native-localize";openAppLanguageSettings("application").catch((error)=>{console.warn("Cannot open app language settings",error);});

Examples with @formatjs/intl

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:

// __mocks__/react-native-localize.tsexport*from"react-native-localize/mock";// or "react-native-localize/mock/jest"

Sponsors

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.