Awesome Open Source
Awesome Open Source

🌍  react-native-localize

A toolbox for your React Native app localization.

npm version npm MIT
Platform - Android Platform - iOS Platform - macOS Platform - Windows Platform - Web


This library helped you? Consider sponsoring!

This module is provided as is, I work on it in my free time.

If 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.


package name version react-native version
react-native-localize 2.0.0+ 0.60.0+
react-native-localize 1.0.0+ 0.56.0+


$ npm install --save react-native-localize
# --- or ---
$ yarn add react-native-localize

Don't forget to run pod install after that !

🆘  Manual linking

Because this package targets React Native 0.60.0+, you will probably don't need to link it manually. Otherwise if it's not the case, follow this additional instructions:

👀 See manual linking instructions


Add this line to your ios/Podfile file, then run pod install.

target 'YourAwesomeProject' do
  # …
  pod 'RNLocalize', :path => '../node_modules/react-native-localize'


  1. Add the following lines to android/settings.gradle:
include ':react-native-localize'
project(':react-native-localize').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-localize/android')
  1. Add the implementation line to the dependencies in android/app/build.gradle:
dependencies {
  // ...
  implementation project(':react-native-localize')
  1. Add the import and link the package in
import com.zoontek.rnlocalize.RNLocalizePackage; // <- add the RNLocalizePackage import

public class MainApplication extends Application implements ReactApplication {

  // …

  protected List<ReactPackage> getPackages() {
    List<ReactPackage> packages = new PackageList(this).getPackages();
    // …
    packages.add(new RNLocalizePackage());
    return packages;

  // …


Add this line to your macos/Podfile file, then run pod install.

target 'YourAwesomeProject' do
  # …
  pod 'RNLocalize', :path => '../node_modules/react-native-localize'

Windows Support

Because this RNW package targets React Native 0.63.0+, you probably won't need to link it manually. Otherwise if it's not the case, follow these additional instructions. You also need to manually link the module on Windows when using React Native Windows prior to 0.63:

For more information about autolinking and manual linking. Follow the official guide

Web support

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

Basic usage example

import * as RNLocalize from "react-native-localize";


RNLocalize.addEventListener("change", () => {
  // do localization related stuff…



Returns the user preferred locales, in order.

Method type

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

Usage example

/* -> [
  { 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 },
] */


Returns number formatting settings.

Method type

type getNumberFormatSettings = () => {
  decimalSeparator: string;
  groupingSeparator: string;

Usage example

/* -> {
  decimalSeparator: ".",
  groupingSeparator: ",",
} */


Returns the user preferred currency codes, in order.

Method type

type getCurrencies = () => Array<string>;

Usage example

// -> ["EUR", "GBP", "USD"]


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

Method type

type getCountry = () => string;

Usage example

// -> "FR"


Devices using Latin American regional settings will return "UN" instead of "419", as the latter is not a standard country code.


Returns the user preferred calendar format.

Method type

type getCalendar = () => "gregorian" | "japanese" | "buddhist";

Usage example

// -> "gregorian"


Returns the user preferred temperature unit.

Method type

type getTemperatureUnit = () => "celsius" | "fahrenheit";

Usage example

// -> "celsius"


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

Method type

type getTimeZone = () => string;

Usage example

// -> "Europe/Paris"


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

Method type

type uses24HourClock = () => boolean;

Usage example

// -> true


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

Method type

type usesMetricSystem = () => boolean;

Usage example

// -> true


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

Method type

type Option<T> = T | undefined;
type usesAutoDateAndTime = () => Option<boolean>;

Usage example

console.log(RNLocalize.usesAutoDateAndTime()); // true or false


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

Method type

type Option<T> = T | undefined;
type usesAutoTimeZone = () => Option<boolean>;

Usage example


addEventListener() / removeEventListener()

Allows you to listen for any localization change.

Methods type

type addEventListener = (type: "change", handler: Function) => void;
type removeEventListener = (type: "change", handler: Function) => void;

Usage example

function handleLocalizationChange() {

RNLocalize.addEventListener("change", handleLocalizationChange);
// …later (ex: component unmount)
RNLocalize.removeEventListener("change", handleLocalizationChange);


Returns the best language tag possible and its reading direction (⚠️ it respects the user preferred languages list order, see explanations). Useful to pick the best translation available.

Method type

type findBestAvailableLanguage = (
  languageTags: Array<string>,
) => { languageTag: string; isRTL: boolean } | void;

Usage example

console.log(RNLocalize.findBestAvailableLanguage(["en-US", "en", "fr"]));
// -> { languageTag: "en-US", isRTL: false }

Examples with i18n-js

Browse the files in the /example directory.

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 use in your __mocks__/react-native-localize.js or jest.setup.js.

import RNLocalize from "react-native-localize/mock";

jest.mock("react-native-localize", () => RNLocalize);

Add project's supported localizations (iOS)

Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Java (388,770
Reactjs (162,620
User (47,289
Types (30,029
Localization (5,329
I18n (4,838
Internationalization (3,330
Language Detection (280
Globalization (169