zoontek/react-native-localize

README

🌍 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 !

iOS

List your supported locales under CFBundleLocalizations in ios/YourApp/Info.plist:

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

Android

Set android:localeConfig on the <application> element in android/app/src/main/AndroidManifest.xml:

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

Then list your supported locales in android/app/src/main/res/xml/locale_config.xml:

<?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

Specify the supported locales in your app.json or app.config.js using the config plugin.

Dynamic configuration (app.config.js, app.config.ts)

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"] }
    }),
  ],
});

Static configuration (app.json)

{
  "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()

Returns the user preferred calendar format.

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

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

Method type

type getCountry = () => 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.

getCurrencies()

Returns the user preferred currency codes, in order.

Method type

type getCurrencies = () => string[];

Usage example

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

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

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

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

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

Usage example

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

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

getTemperatureUnit()

Returns the user preferred temperature unit.

Method type

type getTemperatureUnit = () => "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

type getTimeZone = () => 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

type uses24HourClock = () => 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

type usesMetricSystem = () => 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

type usesAutoDateAndTime = () => 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

type usesAutoTimeZone = () => 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

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

Opens the app language settings.

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

On the client, react-native-localize uses navigator.languages. During SSR, it gets language preferences from the server via the parsed Accept-Language header.

1. Wrap your app with `ServerLanguagesProvider`

On the server, wrap your app with ServerLanguagesProvider and pass the user's languages:

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

In your components, use the useLocalize hook instead of calling the API methods directly:

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

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

Examples with @formatjs/intl

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 import in your __mocks__ directory:

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

🌍 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 !

iOS

List your supported locales under CFBundleLocalizations in ios/YourApp/Info.plist:

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

Android

Set android:localeConfig on the <application> element in android/app/src/main/AndroidManifest.xml:

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

Then list your supported locales in android/app/src/main/res/xml/locale_config.xml:

<?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

Specify the supported locales in your app.json or app.config.js using the config plugin.

Dynamic configuration (app.config.js, app.config.ts)

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"] }
    }),
  ],
});

Static configuration (app.json)

{
  "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()

Returns the user preferred calendar format.

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

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

Method type

type getCountry = () => 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.

getCurrencies()

Returns the user preferred currency codes, in order.

Method type

type getCurrencies = () => string[];

Usage example

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

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

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

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

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

Usage example

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

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

getTemperatureUnit()

Returns the user preferred temperature unit.

Method type

type getTemperatureUnit = () => "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

type getTimeZone = () => 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

type uses24HourClock = () => 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

type usesMetricSystem = () => 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

type usesAutoDateAndTime = () => 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

type usesAutoTimeZone = () => 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

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

Opens the app language settings.

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

On the client, react-native-localize uses navigator.languages. During SSR, it gets language preferences from the server via the parsed Accept-Language header.

1. Wrap your app with `ServerLanguagesProvider`

On the server, wrap your app with ServerLanguagesProvider and pass the user's languages:

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

In your components, use the useLocalize hook instead of calling the API methods directly:

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

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

Examples with @formatjs/intl

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 import in your __mocks__ directory:

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