README.md

🌍  react-native-localize

A toolbox for your React Native app localization.

⚠️  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

Installation

Using yarn

$ 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_modules ➜ react-native-localize ➜ ios ➜ 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')

2. Add the compile line to the dependencies in android/app/build.gradle:

dependencies {
  // ...
  compile project(':react-native-localize')
}

3. 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 },
] */

---

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 }

Add project's supported localizations (iOS)

Examples with i18n-js

Browse the files in the /example directory.