gem-hunter

🌍  react-native-localize

Support

Setup

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

iOS

<key>CFBundleLocalizations</key>
<array>
  <string>en</string>
  <string>fr</string>
</array>

Android

<application android:localeConfig="@xml/locale_config" />

<?xml version="1.0" encoding="utf-8"?>
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
  <locale android:name="en" />
  <locale android:name="fr" />
</locale-config>

Expo

import type { ConfigContext, ExpoConfig } from "expo/config";
import localize from "react-native-localize/expo"; // use `require` in app.config.js

export default ({ config }: ConfigContext): ExpoConfig => ({
  plugins: [
    localize({
      locales: ["en", "fr"], // or { android: ["en"], ios: ["en", "fr"] }
    }),
  ],
});

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

Basic usage example

import { getCurrencies, getLocales } from "react-native-localize";

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

API

getCalendar()

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

getCountry()

Method type

type getCountry = () => string;

Usage example

import { getCountry } from "react-native-localize";

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

Note

getCurrencies()

Method type

type getCurrencies = () => string[];

Usage example

import { getCurrencies } from "react-native-localize";

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

getLocales()

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());
/* -> [
  { 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()

Method type

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

Usage example

import { getNumberFormatSettings } from "react-native-localize";

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

getTemperatureUnit()

Method type

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

Usage example

import { getTemperatureUnit } from "react-native-localize";

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

getTimeZone()

Method type

type getTimeZone = () => string;

Usage example

import { getTimeZone } from "react-native-localize";

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

uses24HourClock()

Method type

type uses24HourClock = () => boolean;

Usage example

import { uses24HourClock } from "react-native-localize";

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

usesMetricSystem()

Method type

type usesMetricSystem = () => boolean;

Usage example

import { usesMetricSystem } from "react-native-localize";

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

usesAutoDateAndTime()

Method type

type usesAutoDateAndTime = () => boolean | undefined;

Usage example

import { usesAutoDateAndTime } from "react-native-localize";

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

usesAutoTimeZone()

Method type

type usesAutoTimeZone = () => boolean | undefined;

Usage example

import { usesAutoTimeZone } from "react-native-localize";

console.log(usesAutoTimeZone());

findBestLanguageTag()

Note

It respects the user preferred languages list order (see explanations).

Method type

type findBestLanguageTag = (
  languageTags: string[],
) => { languageTag: string; isRTL: boolean } | undefined;

Usage example

import { findBestLanguageTag } from "react-native-localize";

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

openAppLanguageSettings()

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);
});

Server-side rendering

1. Wrap your app with ServerLanguagesProvider

import accepts from "accepts";
import { ServerLanguagesProvider } from "react-native-localize";

// parse the Accept-Language header; any approach returning string[] is fine
const languages = accepts(request).languages();

const html = renderToString(
  <ServerLanguagesProvider value={languages}>
    <App />
  </ServerLanguagesProvider>,
);

2. Use the useLocalize hook in your components

import { useLocalize } from "react-native-localize";

const App = () => {
  const { getCountry } = useLocalize();
  return <Text>Country: {getCountry()}</Text>;
};

Examples with @formatjs/intl

How to test your code

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

Sponsors