0
# React Native Localize
1
2
React Native Localize is a comprehensive toolbox for React Native app localization, providing access to device-specific regional settings including preferred locales, currencies, number formatting, calendar systems, temperature units, timezones, and measurement systems. It offers cross-platform support for Android, iOS, macOS, and Web with automatic language detection, RTL text support, and intelligent language tag matching.
3
4
## Package Information
5
6
- **Package Name**: react-native-localize
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-localize`
10
11
## Core Imports
12
13
```typescript
14
import {
15
getLocales,
16
getCountry,
17
getCurrencies,
18
findBestLanguageTag,
19
getNumberFormatSettings,
20
getCalendar,
21
getTemperatureUnit,
22
getTimeZone,
23
uses24HourClock,
24
usesMetricSystem,
25
usesAutoDateAndTime,
26
usesAutoTimeZone,
27
openAppLanguageSettings,
28
type Locale,
29
type Calendar,
30
type TemperatureUnit,
31
type NumberFormatSettings
32
} from "react-native-localize";
33
```
34
35
For CommonJS:
36
37
```javascript
38
const {
39
getLocales,
40
getCountry,
41
getCurrencies,
42
findBestLanguageTag
43
} = require("react-native-localize");
44
```
45
46
## Basic Usage
47
48
```typescript
49
import { getLocales, findBestLanguageTag, getNumberFormatSettings } from "react-native-localize";
50
51
// Get device locales
52
const locales = getLocales();
53
console.log(locales[0]); // { languageCode: "en", countryCode: "US", languageTag: "en-US", isRTL: false }
54
55
// Find best matching language
56
const bestLanguage = findBestLanguageTag(["en-US", "fr-FR", "es-ES"]);
57
console.log(bestLanguage); // { languageTag: "en-US", isRTL: false }
58
59
// Get number formatting
60
const numberFormat = getNumberFormatSettings();
61
console.log(numberFormat); // { decimalSeparator: ".", groupingSeparator: "," }
62
```
63
64
## Architecture
65
66
React Native Localize is built around several key components:
67
68
- **Native Bridge**: TurboModule interface connecting JavaScript to native platform APIs
69
- **Web Implementation**: Browser-based implementation using Intl and Navigator APIs for web compatibility
70
- **Type System**: Complete TypeScript definitions for all APIs and data structures
71
- **Platform Detection**: Automatic platform-specific behavior for iOS, Android, macOS, and Web
72
- **Mock System**: Testing utilities with configurable mock implementations
73
- **Expo Integration**: Plugin for configuring supported locales in Expo managed workflow
74
75
## Capabilities
76
77
### Device Settings
78
79
Core functionality for accessing device regional settings including locales, country, timezone, and calendar information.
80
81
```typescript { .api }
82
function getLocales(): Locale[];
83
function getCountry(): string;
84
function getTimeZone(): string;
85
function getCalendar(): Calendar;
86
```
87
88
[Device Settings](./device-settings.md)
89
90
### Language Matching
91
92
Intelligent language tag matching to find the best supported language from your app's available translations.
93
94
```typescript { .api }
95
function findBestLanguageTag<T extends string>(
96
languageTags: ReadonlyArray<T>
97
): { languageTag: T; isRTL: boolean } | undefined;
98
```
99
100
[Language Matching](./language-matching.md)
101
102
### Number and Currency Formatting
103
104
Access to device-specific number formatting preferences and regional currency information.
105
106
```typescript { .api }
107
function getNumberFormatSettings(): NumberFormatSettings;
108
function getCurrencies(): string[];
109
110
interface NumberFormatSettings {
111
decimalSeparator: string;
112
groupingSeparator: string;
113
}
114
```
115
116
[Number and Currency Formatting](./number-currency-formatting.md)
117
118
### Device Preferences
119
120
System preferences for measurement units, time format, and automatic settings.
121
122
```typescript { .api }
123
function getTemperatureUnit(): TemperatureUnit;
124
function uses24HourClock(): boolean;
125
function usesMetricSystem(): boolean;
126
function usesAutoDateAndTime(): boolean | undefined;
127
function usesAutoTimeZone(): boolean | undefined;
128
```
129
130
[Device Preferences](./device-preferences.md)
131
132
### Platform Utilities
133
134
Platform-specific functionality including settings access and testing utilities.
135
136
```typescript { .api }
137
function openAppLanguageSettings(): Promise<void>;
138
```
139
140
[Platform Utilities](./platform-utilities.md)
141
142
## Types
143
144
```typescript { .api }
145
interface Locale {
146
languageCode: string;
147
scriptCode?: string;
148
countryCode: string;
149
languageTag: string;
150
isRTL: boolean;
151
}
152
153
interface NumberFormatSettings {
154
decimalSeparator: string;
155
groupingSeparator: string;
156
}
157
158
type TemperatureUnit = "celsius" | "fahrenheit";
159
160
type Calendar =
161
| "gregorian"
162
| "buddhist"
163
| "coptic"
164
| "ethiopic"
165
| "ethiopic-amete-alem"
166
| "hebrew"
167
| "indian"
168
| "islamic"
169
| "islamic-umm-al-qura"
170
| "islamic-civil"
171
| "islamic-tabular"
172
| "iso8601"
173
| "japanese"
174
| "persian";
175
```