expo-localization

What is expo-localization?

The expo-localization package provides utilities for determining the locale, language, and region settings of a user's device. It is useful for internationalizing and localizing applications to provide a more personalized user experience.

What are expo-localization's main functionalities?

Get current locale

This feature allows you to get the current locale of the user's device. The locale is a string that represents the language and region settings, such as 'en-US' for English (United States).

import * as Localization from 'expo-localization';

console.log(Localization.locale);

Get preferred languages

This feature provides an array of preferred languages set on the user's device. This can be useful for applications that support multiple languages and want to prioritize content based on user preferences.

import * as Localization from 'expo-localization';

console.log(Localization.locales);

Get timezone

This feature allows you to get the current timezone of the user's device. The timezone is a string that represents the time zone identifier, such as 'America/Los_Angeles'.

import * as Localization from 'expo-localization';

console.log(Localization.timezone);

Get country

This feature provides the country code of the user's device, such as 'US' for the United States. This can be useful for region-specific content or services.

import * as Localization from 'expo-localization';

console.log(Localization.country);

Other packages similar to expo-localization

react-native-localize

The react-native-localize package provides similar functionalities for determining the locale, language, and region settings of a user's device. It offers more comprehensive support for React Native applications and includes additional features like currency and calendar type detection.

i18next

The i18next package is a powerful internationalization framework for JavaScript applications. While it does not directly provide device locale information, it integrates well with localization packages to manage translations and language switching in applications.

globalize

The globalize package is a comprehensive library for internationalization and localization in JavaScript. It provides functionalities for formatting numbers, dates, and strings based on locale settings. It can be used in conjunction with device locale detection packages to provide a complete localization solution.

README

expo-localization

expo-localization enables you to interface with the native device locale.

Installation

Now, you need to install the package from npm registry.

npm install expo-localization or yarn add expo-localization

iOS (Cocoapods)

If you're using Cocoapods, add the dependency to your Podfile:

pod 'EXLocalization', path: '../node_modules/expo-localization/ios'

and if not already included

pod 'EXCore', path: '../node_modules/expo-core/ios'

and run pod install.

Android

1. Append the following lines to android/settings.gradle:

   include ':expo-localization'
   project(':expo-localization').projectDir = new File(rootProject.projectDir, '../node_modules/expo-localization/android')
   

   and if not already included

   include ':expo-core'
   project(':expo-core').projectDir = new File(rootProject.projectDir, '../node_modules/expo-core/android')
   

2. Insert the following lines inside the dependencies block in android/app/build.gradle:

   api project(':expo-localization')
   

   and if not already included

   api project(':expo-core')
   

Some Unimodules are not included in the default ExpoKit suite, these modules will needed to be added manually. If your Android build cannot find the Native Modules, you can add them like this:

./android/app/src/main/java/host/exp/exponent/MainActivity.java

@Override
public List<Package> expoPackages() {
  // Here you can add your own packages.
  return Arrays.<Package>asList(
    new LocalizationPackage() // Include this.
  );
}

Usage

import React from 'react';
import { Text } from 'react-native';
import { Localization } from 'expo-localization';

import i18n from 'i18n-js';

const en = {
  foo: 'Foo',
  bar: 'Bar {{someValue}}',
};

const fr = {
  foo: 'como telle fous',
  bar: 'chatouiller {{someValue}}',
};

i18n.fallbacks = true;
i18n.translations = { fr, en };
i18n.locale = Localization.locale;

export default class LitView extends React.Component {
  componentWillMount() {
    this._subscription = Localization.addListener(({ locale }) => {
      i18n.locale = locale;
    });
  }

  componentWillUnmount() {
    if (!!this._subscription) {
      this._subscription.remove();
    }
  }

  render() {
    return (
      <Text>
        {i18n.t('foo')} {i18n.t('bar', { someValue: Date.now() })}
      </Text>
    );
  }
}

API

Constants

This API is mostly synchronous and driven by constants.

Localization.locale: string

Native device language, returned in standard format. ex: en-US, es-US.

Localization.locales: Array<string>

List of all the native languages provided by the user settings. These are returned in the order the user defines in their native settings.

Localization.country: ?string

Country code for your device.

Localization.isoCurrencyCodes: ?Array<string>

A list of all the supported ISO codes.

Localization.timezone: string

The current time zone in display format. ex: America/Los_Angeles

Localization.isRTL: boolean

This will return true if the current language is Right-to-Left.

Methods

Callbacks are Android only, changing the native locale on iOS will cause all the apps to reset.

Localization.addListener(listener: Listener): ?Subscription

Observe when a language is added or moved in the Android settings.

Localization.removeAllListeners(): void

Clear all language observers.

Localization.removeSubscription(subscription: Subscription): void

Stop observing when the native languages are edited.