react-native-localize - Amazon Vega Docs

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:

Handle multiple languages
Set date and time formats
Set currency
Manage other regional settings

The @amazon-devices/react-native-localize library uses Localize React Native in React Native for Vega (RNV) 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

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

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

Import getCurrencies into your preferred component:

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

Run npm install on your project root to install the package.
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.

Method	Simulator	Device
`getLocales`	Same	Same
`getCurrencies`	Same	Same
`getCountry`	Fixed value	Based on device
`getTimeZone`	Fixed value	Based on device
`getCalendar`	Fixed value	Based on device

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

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.

languageCode
scriptCode
languageTag
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

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: Screenshot showing the output on a simulator, displaying locale information such as language tag, language code, country code and if there is RTL or not.

Screenshot showing the output on a simulator, displaying locale information such as language tag, language code, country code and if there is RTL or not.

getNumberFormatSettings()

Returns number formatting settings.

Method type

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

Example

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

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

getCurrencies()

Returns a list of all currencies.

Method type

type getCurrencies = () => string[];

Example

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

type getCountry = () => string;

Example 1

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:

The getCountry() method from @amazon-devices/react-native-localize to get the country from the device.
The useState() method to save the country code.
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.

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: Screenshot that shows the output on a Vega simulator device, displaying the IN country code and message.

Screenshot that shows the output on a Vega simulator device, displaying the US country code and message.

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

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

Example

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

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

getTemperatureUnit()

Returns the user’s preferred temperature unit.

Method type

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

Example

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

type getTimeZone = () => string;

Example

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

type uses24HourClock = () => boolean;

Example

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

type usesMetricSystem = () => boolean;

Example

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

type usesAutoDateAndTime = () => boolean | undefined;

Example

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

type usesAutoTimeZone = () => boolean | undefined;

Example

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


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

Supported versions

Package name	Amazon NPM library version	Vega OS build number	Vega SDK version	Release notes
`@amazon-devices/react-native-localize`	2.0.1+3.0.4	OS 1.1 (201010438050)	0.20

Supported Third-Party Libraries and Services
react-native-device-info — To retrieve device and app information such as OS version, device model, app version, and bundle ID, use the react-native-device-info package alongside react-native-localize.

​Why Localize Your TV App?

​Installation

​Examples

​Simulator versus device

​API reference

​getLocales()

​Method type

​Example

​getNumberFormatSettings()

​Method type

​Example

​getCurrencies()

​Method type

​Example

​getCountry()

​Method type

​Example 1

​Example 2

​Latin American regions

​getCalendar()

​Method type

​Example

​getTemperatureUnit()

​Method type

​Example

​getTimeZone()

​Method type

​Example

​uses24HourClock()

​Method type

​Example

​usesMetricSystem()

​Method type

​Example

​usesAutoDateAndTime()

​Method type

​Example

​usesAutoTimeZone()

​Method type

​Example

​Supported versions

​Related topics

Why Localize Your TV App?

Installation

Examples

Simulator versus device

API reference

getLocales()

Method type

Example

getNumberFormatSettings()

Method type

Example

getCurrencies()

Method type

Example

getCountry()

Method type

Example 1

Example 2

Latin American regions

getCalendar()

Method type

Example

getTemperatureUnit()

Method type

Example

getTimeZone()

Method type

Example

uses24HourClock()

Method type

Example

usesMetricSystem()

Method type

Example

usesAutoDateAndTime()

Method type

Example

usesAutoTimeZone()

Method type

Example

Supported versions

Related topics