Skip to content
🌍 A toolbox for your React Native app localization (formerly react-native-languages)
Branch: master
Clone or download
Latest commit 34c6654 May 4, 2019

README.md

🌍  react-native-localize

A toolbox for your React Native app localization.

npm version npm Platform - Android and iOS MIT styled with prettier

⚠️  Breaking change

This project was known as react-native-languages and has been renamed to reflect new APIs possibilities.
Find more informations about this change here.

Support

package name version react-native version
react-native-localize 1.0.0+ 0.56.0+
react-native-languages 2.0.1 0.48.0 - 0.55.4

Setup

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

Linking

Using react-native-cli (recommended)

$ react-native link react-native-localize

Manual (iOS)

  1. In the XCode's "Project navigator", right click on your project's Libraries folder ➜ Add Files to <...>
  2. Go to node_modulesreact-native-localizeios ➜ select RNLocalize.xcodeproj
  3. Add RNLocalize.a to Build Phases -> Link Binary With Libraries

Manual (Android)

  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 compile line to the dependencies in android/app/build.gradle:
dependencies {
  // ...
  implementation project(':react-native-localize')
}
  1. Add the import and link the package in MainApplication.java:
import com.reactcommunity.rnlocalize.RNLocalizePackage; // <-- Add the RNLocalize import

public class MainApplication extends Application implements ReactApplication {

  //

  @Override
  protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
      new MainReactPackage(),
      //
      new RNLocalizePackage() // <-- Add it to the packages list
    );
  }

  //
}

Basic usage example

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

console.log(RNLocalize.getLocales());
console.log(RNLocalize.getCurrencies());

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

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

console.log(RNLocalize.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

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

Usage example

console.log(RNLocalize.getNumberFormatSettings());
/* -> {
  decimalSeparator: ".",
  groupingSeparator: ",",
} */

getCurrencies()

Returns the user preferred currency codes, in order.

Method type

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

Usage example

console.log(RNLocalize.getCurrencies());
// -> ["EUR", "GBP", "USD"]

getCountry()

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

Method type

type getCountry = () => string;

Usage example

console.log(RNLocalize.getCountry());
// -> "FR"

getCalendar()

Returns the user preferred calendar format.

Method type

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

Usage example

console.log(RNLocalize.getCalendar());
// -> "gregorian"

getTemperatureUnit()

Returns the user preferred temperature unit.

Method type

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

Usage example

console.log(RNLocalize.getTemperatureUnit());
// -> "celsius"

getTimeZone()

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

Method type

type getTimeZone = () => string;

Usage example

console.log(RNLocalize.getTimeZone());
// -> "Europe/Paris"

uses24HourClock()

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

Method type

type uses24HourClock = () => boolean;

Usage example

console.log(RNLocalize.uses24HourClock());
// -> true

usesMetricSystem()

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

Method type

type usesMetricSystem = () => boolean;

Usage example

console.log(RNLocalize.usesMetricSystem());
// -> true

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() {
  console.log(RNLocalize.getLocales());
}

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

findBestAvailableLanguage()

Returns the best language tag possible and its direction (if it can find one). Useful to choose 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 might need to mock this package to run your tests flawlessly.
Here is an example for Jest, adapt it to your needs :

// __mocks__/react-native-localize.js

const getLocales = () => [
  // you can choose / add the locales you want
  { countryCode: "US", languageTag: "en-US", languageCode: "en", isRTL: false },
  { countryCode: "FR", languageTag: "fr-FR", languageCode: "fr", isRTL: false },
];

// use a provided translation, or return undefined to test your fallback
const findBestAvailableLanguage = () => ({ languageTag: 'en-US', isRTL: false });

const getNumberFormatSettings = () => ({
  decimalSeparator: ".",
  groupingSeparator: ",",
});

const getCalendar = () => "gregorian"; // or "japanese", "buddhist"
const getCountry = () => "US"; // the country code you want
const getCurrencies = () => ["USD", "EUR"]; // can be empty array
const getTemperatureUnit = () => "celsius"; // or "fahrenheit"
const getTimeZone = () => "Europe/Paris"; // the timezone you want
const uses24HourClock = () => true;
const usesMetricSystem = () => true;

const addEventListener = jest.fn();
const removeEventListener = jest.fn();

export {
  findBestAvailableLanguage,
  getLocales,
  getNumberFormatSettings,
  getCalendar,
  getCountry,
  getCurrencies,
  getTemperatureUnit,
  getTimeZone,
  uses24HourClock,
  usesMetricSystem,
  addEventListener,
  removeEventListener,
};

Add project's supported localizations (iOS)

You can’t perform that action at this time.