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
```