react-native-localize

In this article, you learn how to use the react-native-localize package in your Vega TV app. You can read about the methods supported in the Vega SDK.

The react-native-localize package helps you create a personalized experience for every user, allowing you to:

1. Handle multiple languages
2. Set date and time formats
3. Set currency
4. Manage other regional settings

The @amazon-devices/react-native-localize library uses Localize React Native in React Native for Vega (RNK) apps. This library provides localization and internationalization support, allowing you to adapt your app to different languages, regions, and cultures.

Why Localize Your TV App?

• User Experience: Users prefer apps that speak their language and understand their regional preferences.
• Global Reach: You can increase your app's appeal to a broader audience in international markets.
• Legal Compliance: You can ensure compliance with the regulations of various regions.

Installation

1. Add the react-native-localize package as a dependency in package.json:

   Copy code Copied to clipboard.

      "dependencies": {
            ...
            "@amazon-devices/react-native-localize": "~2.0.0"
      }
   

2. Import getCurrencies into your preferred component:

   Copy code Copied to clipboard.

   import { getCurrencies } from '@amazon-devices/react-native-localize';
   

3. Run npm install on your project root to install the package.

4. After a successful installation, run your Vega project.

Examples

Simulator versus device

Return values for the methods in the react-native-localize package might be different for a simulator than they are for a device. For example, the getCountry() method on a simulator returns US, but for a device, the return value is based on the device's language setting.

Here's an example of how to use @amazon-devices/react-native-localize.

Copy code Copied to clipboard.

import { getCurrencies, getLocales } from "@amazon-devices/react-native-localize";

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

API reference

getLocales()

Returns a list of locales based on the user's device.

1. languageCode
2. scriptCode
3. languageTag
4. isRTL

Method type

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

Possible output:

local: [
{"languageCode":"af","scriptCode":"","countryCode":"","languageTag":"af","isRTL":"false"},
{"languageCode":"af","scriptCode":"","countryCode":"NA","languageTag":"af-NA","isRTL":"false"},
{"languageCode":"af","scriptCode":"","countryCode":"ZA","languageTag":"af-ZA","isRTL":"false"},
{"languageCode":"agq","scriptCode":"","countryCode":"","languageTag":"agq","isRTL":"false"},
{"languageCode":"agq","scriptCode":"","countryCode":"CM","languageTag":"agq-CM","isRTL":"false"},
{"languageCode":"ak","scriptCode":"","countryCode":"","languageTag":"ak","isRTL":"false"},
{"languageCode":"ak","scriptCode":"","countryCode":"GH","languageTag":"ak-GH","isRTL":"false"},
{"languageCode":"am","scriptCode":"","countryCode":"","languageTag":"am","isRTL":"false"},
{"languageCode":"am","scriptCode":"","countryCode":"ET","languageTag":"am-ET","isRTL":"false"},
{"languageCode":"ar","scriptCode":"","countryCode":"","languageTag":"ar","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"AE","languageTag":"ar-AE","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"BH","languageTag":"ar-BH","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"DJ","languageTag":"ar-DJ","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"DZ","languageTag":"ar-DZ","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"EG","languageTag":"ar-EG","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"EH","languageTag":"ar-EH","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"ER","languageTag":"ar-ER","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"IL","languageTag":"ar-IL","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"IQ","languageTag":"ar-IQ","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"JO","languageTag":"ar-JO","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"KM","languageTag":"ar-KM","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"KW","languageTag":"ar-KW","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"LB","languageTag":"ar-LB","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"LY","languageTag":"ar-LY","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"MA","languageTag":"ar-MA","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"MR","languageTag":"ar-MR","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"OM","languageTag":"ar-OM","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"QA","languageTag":"ar-QA","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"PS","languageTag":"ar-PS","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"SA","languageTag":"ar-SA","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"SD","languageTag":"ar-SD","isRTL":"true"},
{"languageCode":"ar","scriptCode":"","countryCode":"SO","languageTag":"ar-SO","isRTL":"true"}
...

Example

Copy code Copied to clipboard.

import React, {useEffect, useState} from 'react';
import {View, Text, StyleSheet} from 'react-native';
import {getLocales} from '@amazon-devices/react-native-localize';

const DeviceLocale= () => {
const [localeInfo, setLocaleInfo] = useState(null);

useEffect(() => {
const locales = getLocales();

if (locales && locales.length > 0) {
const locale = locales[0];
setLocaleInfo({
languageTag: locale.languageTag,
languageCode: locale.languageCode,
countryCode: locale.countryCode,
isRTL: locale.isRTL,
});
}
}, []);

return (
<View style={styles.container}>
<Text style={styles.text}>Locale Information:</Text>
{localeInfo ? (
<View>
<Text style={styles.text}>
Language Tag: {localeInfo.languageTag}
</Text>
<Text style={styles.text}>
Language Code: {localeInfo.languageCode}
</Text>
<Text style={styles.text}>
Country Code: {localeInfo.countryCode}
</Text>
<Text style={styles.text}>
Is RTL: {localeInfo.isRTL ? 'Yes' : 'No'}
</Text>
</View>
) : (
<Text style={styles.text}>Loading locale...</Text>
)}
</View>
);
};

Output:

getNumberFormatSettings()

Returns number formatting settings.

Method type

Copy code Copied to clipboard.

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

Example

Copy code Copied to clipboard.

import { getNumberFormatSettings } from "@amazon-devices/react-native-localize";

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

getCurrencies()

Returns a list of all currencies.

Method type

Copy code Copied to clipboard.

type getCurrencies = () => string[];

Example

Copy code Copied to clipboard.

import { getCurrencies } from "@amazon-devices/react-native-localize";

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

Possible output:

Currency: ["XXX","NAD","ZAR","XAF","GHS","ETB","AED","BHD","DJF","DZD","EGP","MAD","ERN","ILS","IQD","JOD","KMF","KWD","LBP","LYD","MRU","OMR","QAR","SAR","SDG","SOS","SSP","SYP","TND","YER","INR","TZS","EUR","AZN","BYN","ZMW","BGN","XOF","BDT","CNY","BAM","RUB","PHP","UGX","USD","IRR","CZK","GBP","DKK","KES","CHF","BTN","XCD","AUD","BBD","BIF","BMD","BSD","BWP","BZD","CAD","NZD","FJD","FKP","GIP","GMD","GYD","JMD","KYD","LRD","MGA","MOP","MUR","MWK","MYR","NGN","PGK","PKR","RWF","SBD","SCR","SEK","SGD","SHP","SLL","ANG","SZL","TOP","TTD","VUV","WST","ARS","BOB","BRL","CLP","COP","CRC","CUP","DOP","GTQ","HNL","MXN","NIO","PAB","PEN","PYG","UYU","VES","AFN","GNF","CDF","HTG","XPF","HRK","HUF","AMD","IDR","ISK","JPY","GEL","CVE","KZT","KHR","KPW","KRW","TRY","KGS","LAK","MZN","MKD","MNT","BND","MMK","NOK","NPR","AWG","SRD","PLN","STN","MDL","RON","UAH","LKR","ALL","RSD","TJS","THB","TMT","UZS","VND","TWD"]

getCountry()

Returns the user's current country code based on their device's language setting. For example, if the language setting is English India, the country returns as IN.

Note: if you're using a simulator, the Time Zone property outputs Universal.

For example, this output is with a device's language setting set to English India.

local: 786
Currency: INR
Country: IN
Time Zone: Europe/London
24 Hour clock: false
Calendar: gregorian

For example, this output is with a device's language setting set to American English.

Country: US
Time Zone: Universal
24 Hour clock: false
Calendar: gregorian
getTemperatureUnit: fahrenheit
usesMetricSystem: false

Method type

Copy code Copied to clipboard.

type getCountry = () => string;

Example 1

Copy code Copied to clipboard.

import { getCountry } from "@amazon-devices/react-native-localize";

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

Example 2

You can display a custom message to the user based on their device’s location.

In the following code, you can use:

1. The getCountry() method from @amazon-devices/react-native-localize to get the country from the device.
2. The useState() method to save the country code.
3. A switch case to change the message as per the country code.

Note: To change the device location on a device, go to Settings > Preferences > Languages.

Copy code Copied to clipboard.

import React, {useEffect, useState} from 'react';
import {View, Text, StyleSheet} from 'react-native';
import {getCountry} from '@amazon-devices/react-native-localize';

const GetCountry = () => {
const [country, setCountry] = useState(null);
const [message, setMessage] = useState('');

useEffect(() => {
const countryCode = getCountry();
setCountry(countryCode);

switch (countryCode) {
case 'US':
setMessage('Welcome, American user!');
break;
case 'GB':
setMessage('Welcome, British user!');
break;
case 'IN':
setMessage('Namaste, Indian user!');
break;
default:
setMessage('Welcome, global user!');
break;
}
}, []);

return (
<View style={styles.container}>
<Text style={styles.text}>Country Code: {country}</Text>
<Text style={styles.message}>{message}</Text>
</View>
);
};

Output:

Latin American regions

Devices using Latin American regional settings return "UN" instead of "419", because "419" isn't a standard country code.

getCalendar()

Returns the user's preferred calendar format.

Method type

Copy code Copied to clipboard.

type getCalendar = () =>
  | "gregorian"
  | "buddhist"
  | "coptic"
  | "ethiopic"
  | "ethiopic-amete-alem"
  | "hebrew"
  | "indian"
  | "islamic"
  | "islamic-umm-al-qura"
  | "islamic-civil"
  | "islamic-tabular"
  | "iso8601"
  | "japanese"
  | "persian";

Example

Copy code Copied to clipboard.

import { getCalendar } from "@amazon-devices/react-native-localize";

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

getTemperatureUnit()

Returns the user's preferred temperature unit.

Method type

Copy code Copied to clipboard.

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

Example

Copy code Copied to clipboard.

import { getTemperatureUnit } from "@amazon-devices/react-native-localize";

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

getTimeZone()

Returns the user's current timezone based on the country from their device's language setting. A simulator returns a Universal timezone. A TV device returns the timezone set in the device's settings, such as Europe/London.

For example, this output is with a device's language setting set to American English.

Country: US
Time Zone: Universal
24 Hour clock: false
Calendar: gregorian
getTemperatureUnit: fahrenheit
usesMetricSystem: false

Method type

Copy code Copied to clipboard.

type getTimeZone = () => string;

Example

Copy code Copied to clipboard.

import { getTimeZone } from "@amazon-devices/react-native-localize";

console.log(getTimeZone());
// -> "Asia/Yerevan"

uses24HourClock()

Returns true if the user prefers a 24-hour clock format, false if the user prefers a 12-hour clock format.

Method type

Copy code Copied to clipboard.

type uses24HourClock = () => boolean;

Example

Copy code Copied to clipboard.

import { uses24HourClock } from "@amazon-devices/react-native-localize";

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

usesMetricSystem()

Returns true if the user prefers the metric measurement system, false if the user prefers imperial.

Method type

Copy code Copied to clipboard.

type usesMetricSystem = () => boolean;

Example

Copy code Copied to clipboard.

import { usesMetricSystem } from "@amazon-devices/react-native-localize";

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

usesAutoDateAndTime()

Displays whether or not the device enables the automatic date and time setting.

Method type

Copy code Copied to clipboard.

type usesAutoDateAndTime = () => boolean | undefined;

Example

Copy code Copied to clipboard.

import { usesAutoDateAndTime } from "@amazon-devices/react-native-localize";

console.log(usesAutoDateAndTime());
// -> false/true

usesAutoTimeZone()

Displays whether or not the device enables the automatic time zone setting.

Method type

Copy code Copied to clipboard.

type usesAutoTimeZone = () => boolean | undefined;

Example

Copy code Copied to clipboard.

import { usesAutoTimeZone } from "@amazon-devices/react-native-localize";

console.log(usesAutoTimeZone());
// -> false

Supported versions

Related topics

Supported Third-Party Libraries and Services.

Last updated: Dec 22, 2025