React Native Localize

https://github.com/zoontek/react-native-localize
Admin
React Native Localize is a toolbox for React Native applications providing access to native device...
Tokens:4,299
Snippets:56
Trust Score:9.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install react-native-localize

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Install the library using npm or yarn. Remember to run `pod install` after installation.

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

--------------------------------

### Basic Usage: Get Locales and Currencies

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Import and use `getLocales` and `getCurrencies` to retrieve the user's preferred locale and currency information.

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

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

--------------------------------

### Server-Side Rendering Setup

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Wraps the application with `ServerLanguagesProvider` on the server to provide language preferences from the `Accept-Language` header. This enables `react-native-localize` to function correctly during SSR.

```tsx
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>,
);
```

--------------------------------

### Get Number Format Settings

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieves the user's preferred decimal and grouping separators for number formatting. No specific setup is required.

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

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

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

--------------------------------

### Get Temperature Unit

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Returns the user's preferred temperature unit, either 'celsius' or 'fahrenheit'.

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

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

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

--------------------------------

### Get User's Preferred Currencies

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Use `getCurrencies` to get an array of the user's preferred currency codes, ordered by preference.

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

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

--------------------------------

### Get Time Zone

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieves the user's preferred timezone based on device settings, not their current location. Returns a string representing the timezone.

```typescript
type getTimeZone = () => string;
```

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

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

--------------------------------

### Get User's Preferred Calendar

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Use the `getCalendar` function to retrieve the user's preferred calendar format. The function returns a string representing the calendar type.

```typescript
import { getCalendar } from "react-native-localize";

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

--------------------------------

### Get User's Preferred Locales

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieve an array of the user's preferred locales, in order, using `getLocales`. Each locale object contains language code, script code (optional), country code, language tag, and right-to-left (RTL) directionality.

```typescript
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 },
] */
```

--------------------------------

### Get User's Country Code

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieve the user's current country code using `getCountry`. This is based on the device locale, not the user's physical location. Note that Latin American regional settings may return 'UN'.

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

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

--------------------------------

### openAppLanguageSettings()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Opens the application's language settings screen.

```APIDOC
## openAppLanguageSettings()

### Description
Opens the app language settings. This feature is available only on Android 13+ and requires configuring your app's supported locales.

### Method type
```ts
type openAppLanguageSettings = () => Promise<void>;
```

### Usage example
```ts
import { openAppLanguageSettings } from "react-native-localize";

openAppLanguageSettings("application").catch((error) => {
  console.warn("Cannot open app language settings", error);
});
```
```

--------------------------------

### getNumberFormatSettings()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Fetches the device's number formatting settings.

```APIDOC
## getNumberFormatSettings()

### Description
Returns number formatting settings.

### Method type
```ts
type getNumberFormatSettings = () => {
  currency: string;
  groupingSeparator: string;
  decimalSeparator: string;
  useGrouping: boolean;
  minimumIntegerDigits: number;
  minimumFractionDigits: number;
  maximumFractionDigits: number;
  currencySymbol: string;
  internationalCurrencySymbol: string;
  model: string;
};
```
```

--------------------------------

### usesMetricSystem()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Checks if the user prefers the metric system for measurements.

```APIDOC
## usesMetricSystem()

### Description
Returns `true` if the user prefers metric measure system, `false` if they prefer imperial.

### Method type
```ts
type usesMetricSystem = () => boolean;
```

### Usage example
```ts
import { usesMetricSystem } from "react-native-localize";

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

--------------------------------

### Mock react-native-localize for Testing

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Import the default mock for react-native-localize in your `__mocks__` directory to test your code. This is necessary because it's a native module.

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

--------------------------------

### getCurrencies()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Provides an ordered list of the user's preferred currency codes.

```APIDOC
## getCurrencies()

### Description
Returns the user preferred currency codes, in order.

### Method type
```ts
type getCurrencies = () => string[];
```

### Usage example
```ts
import { getCurrencies } from "react-native-localize";

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

--------------------------------

### getNumberFormatSettings()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieves the user's preferred decimal and grouping separators for number formatting.

```APIDOC
## getNumberFormatSettings()

### Description
Returns an object containing the user's preferred decimal and grouping separators for number formatting.

### Method type
```ts
type getNumberFormatSettings = () => {
  decimalSeparator: string;
  groupingSeparator: string;
};
```

### Usage example
```ts
import { getNumberFormatSettings } from "react-native-localize";

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

--------------------------------

### getTemperatureUnit()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Returns the user's preferred unit for temperature measurement.

```APIDOC
## getTemperatureUnit()

### Description
Returns the user preferred temperature unit, either 'celsius' or 'fahrenheit'.

### Method type
```ts
type getTemperatureUnit = () => "celsius" | "fahrenheit";
```

### Usage example
```ts
import { getTemperatureUnit } from "react-native-localize";

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

--------------------------------

### findBestLanguageTag()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Finds the best matching language tag from a provided list based on user preferences.

```APIDOC
## findBestLanguageTag()

### Description
Returns the best language tag possible and its reading direction. Useful to pick the best translation available. It respects the user preferred languages list order.

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

### Usage example
```ts
import { findBestLanguageTag } from "react-native-localize";

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

--------------------------------

### getCalendar()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieves the user's preferred calendar format. This can be one of several predefined calendar systems.

```APIDOC
## getCalendar()

### Description
Returns the user preferred calendar format.

### Method type
```ts
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
```ts
import { getCalendar } from "react-native-localize";

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

--------------------------------

### Open App Language Settings

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Opens the app's language settings screen. This feature requires Android 13+ and specific app locale configuration.

```typescript
type openAppLanguageSettings = () => Promise<void>;
```

```typescript
import { openAppLanguageSettings } from "react-native-localize";

openAppLanguageSettings("application").catch((error) => {
  console.warn("Cannot open app language settings", error);
});
```

--------------------------------

### Expo Static Configuration

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Configure supported locales statically in `app.json` using the Expo plugin. This enables Android 13+ and iOS to display available locales in system settings.

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

--------------------------------

### uses24HourClock()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Determines if the user prefers a 24-hour clock format.

```APIDOC
## uses24HourClock()

### Description
Returns `true` if the user prefers 24h clock format, `false` if they prefer 12h clock format.

### Method type
```ts
type uses24HourClock = () => boolean;
```

### Usage example
```ts
import { uses24HourClock } from "react-native-localize";

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

--------------------------------

### usesAutoDateAndTime()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Checks if automatic date and time settings are enabled on Android devices.

```APIDOC
## usesAutoDateAndTime()

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

### Method type
```ts
type usesAutoDateAndTime = () => boolean | undefined;
```

### Usage example
```ts
import { usesAutoDateAndTime } from "react-native-localize";

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

--------------------------------

### Expo Dynamic Configuration

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Configure supported locales dynamically in `app.config.js` or `app.config.ts` using the Expo plugin. This allows Android 13+ and iOS to display available locales in system settings.

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

--------------------------------

### Uses Metric System

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Determines if the user prefers the metric system. Returns `true` for metric and `false` for imperial.

```typescript
type usesMetricSystem = () => boolean;
```

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

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

--------------------------------

### Uses Auto Date and Time (Android)

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Checks if automatic date and time settings are enabled on an Android device. Returns `true`, `false`, or `undefined` if the setting is not available.

```typescript
type usesAutoDateAndTime = () => boolean | undefined;
```

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

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

--------------------------------

### getTimeZone()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieves the user's preferred time zone from device settings.

```APIDOC
## getTimeZone()

### Description
Returns the user preferred timezone based on device settings, not the device's current geographical position.

### Method type
```ts
type getTimeZone = () => string;
```

### Usage example
```ts
import { getTimeZone } from "react-native-localize";

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

--------------------------------

### getLocales()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Retrieves an ordered list of the user's preferred locales, including language, script (optional), country codes, and RTL (Right-to-Left) directionality.

```APIDOC
## getLocales()

### Description
Returns the user preferred locales, in order.

### Method type
```ts
type getLocales = () => Array<{ 
  languageCode: string;
  scriptCode?: string;
  countryCode: string;
  languageTag: string;
  isRTL: boolean;
}>;
```

### Usage example
```ts
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 },
] */
```
```

--------------------------------

### Use Localize Hook in Components

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Demonstrates using the `useLocalize` hook within components to access localization methods, such as `getCountry`, instead of calling the API directly. This hook is intended for use within applications configured with `ServerLanguagesProvider`.

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

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

--------------------------------

### Find Best Language Tag

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Finds the best matching language tag from a provided list based on user preferences and indicates if the language is right-to-left (RTL). Useful for selecting translations.

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

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

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

--------------------------------

### getCountry()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Fetches the user's current country code based on their device's locale settings. Note that certain regional settings may result in a non-standard country code.

```APIDOC
## getCountry()

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

### Method type
```ts
type getCountry = () => string;
```

### Usage example
```ts
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.
```

--------------------------------

### Uses 24 Hour Clock

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Checks if the user prefers a 24-hour clock format. Returns `true` for 24h format and `false` for 12h format.

```typescript
type uses24HourClock = () => boolean;
```

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

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

--------------------------------

### Uses Auto Time Zone (Android)

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Checks if the automatic time zone setting is enabled on an Android device. Returns `true`, `false`, or `undefined` if the setting is not available.

```typescript
type usesAutoTimeZone = () => boolean | undefined;
```

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

console.log(usesAutoTimeZone());
```

--------------------------------

### usesAutoTimeZone()

Source: https://github.com/zoontek/react-native-localize/blob/master/README.md

Checks if automatic time zone settings are enabled on Android devices.

```APIDOC
## usesAutoTimeZone()

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

### Method type
```ts
type usesAutoTimeZone = () => boolean | undefined;
```

### Usage example
```ts
import { usesAutoTimeZone } from "react-native-localize";

console.log(usesAutoTimeZone());
```
```
Tokens:
Raw