0
# Internationalization
1

2
Complete internationalization support with locale files for 25+ languages and customizable country/UI labels. The library provides comprehensive localization for country names, UI elements, and supports multiple locale loading patterns.
3

4
## Capabilities
5

6
### Locale Files
7

8
Pre-built locale files containing translated country names and UI labels.
9

10
```typescript { .api }
11
/**
12
 * Locale label structure
13
 * Contains country names and UI element labels
14
 */
15
type Labels = Partial<Record<LabelKey, string>>;
16
type LabelKey = Country | 'ZZ' | 'ext' | 'country' | 'phone';
17

18
// Available locale imports
19
declare const ar: Labels;    // Arabic
20
declare const ca: Labels;    // Catalan  
21
declare const cz: Labels;    // Czech
22
declare const de: Labels;    // German
23
declare const el: Labels;    // Greek
24
declare const en: Labels;    // English
25
declare const es: Labels;    // Spanish
26
declare const et: Labels;    // Estonian
27
declare const fi: Labels;    // Finnish
28
declare const fr: Labels;    // French
29
declare const he: Labels;    // Hebrew
30
declare const hy: Labels;    // Armenian
31
declare const it: Labels;    // Italian
32
declare const ja: Labels;    // Japanese
33
declare const ko: Labels;    // Korean
34
declare const nb: Labels;    // Norwegian Bokmål
35
declare const nl: Labels;    // Dutch
36
declare const pl: Labels;    // Polish
37
declare const pt: Labels;    // Portuguese
38
declare const pt_BR: Labels; // Portuguese (Brazil)
39
declare const ru: Labels;    // Russian
40
declare const sk: Labels;    // Slovak
41
declare const sv: Labels;    // Swedish
42
declare const th: Labels;    // Thai
43
declare const tr: Labels;    // Turkish
44
declare const ua: Labels;    // Ukrainian
45
declare const vi: Labels;    // Vietnamese
46
declare const zh: Labels;    // Chinese
47
```
48

49
**Basic Locale Usage:**
50

51
```typescript
52
import PhoneInput from "react-phone-number-input";
53
import en from "react-phone-number-input/locale/en.json";
54
import de from "react-phone-number-input/locale/de.json";
55
import fr from "react-phone-number-input/locale/fr.json";
56

57
// English locale
58
function EnglishExample() {
59
  const [value, setValue] = useState();
60
  return (
61
    <PhoneInput
62
      value={value}
63
      onChange={setValue}
64
      labels={en}
65
      defaultCountry="US"
66
    />
67
  );
68
}
69

70
// German locale
71
function GermanExample() {
72
  const [value, setValue] = useState();
73
  return (
74
    <PhoneInput
75
      value={value}
76
      onChange={setValue}
77
      labels={de}
78
      defaultCountry="DE"
79
    />
80
  );
81
}
82

83
// French locale
84
function FrenchExample() {
85
  const [value, setValue] = useState();
86
  return (
87
    <PhoneInput
88
      value={value}
89
      onChange={setValue}
90
      labels={fr}
91
      defaultCountry="FR"
92
    />
93
  );
94
}
95
```
96

97
### Locale Import Patterns
98

99
Multiple import patterns are supported for different build systems.
100

101
```typescript { .api }
102
// JSON imports (recommended)
103
import en from "react-phone-number-input/locale/en.json";
104
import de from "react-phone-number-input/locale/de.json";
105

106
// Module imports
107
import en from "react-phone-number-input/locale/en";
108
import de from "react-phone-number-input/locale/de";
109

110
// CommonJS requires
111
const en = require("react-phone-number-input/locale/en.json");
112
const de = require("react-phone-number-input/locale/de.json");
113
```
114

115
### Multiple Locale Support
116

117
The `locales` prop enables automatic locale resolution from browser preferences.
118

119
```typescript { .api }
120
/**
121
 * Locale property supporting single or multiple locales
122
 * Automatically selects best match from browser language preferences
123
 */
124
type LocaleProperty = string | string[];
125

126
interface LocaleProps {
127
  /** Single locale string or array of locales for automatic selection */
128
  locales?: LocaleProperty;
129
  /** Explicit labels object (takes precedence over locales) */
130
  labels?: Labels;
131
}
132
```
133

134
**Multi-Locale Examples:**
135

136
```typescript
137
import PhoneInput from "react-phone-number-input";
138
import "react-phone-number-input/style.css";
139

140
// Automatic locale selection from browser
141
function AutoLocaleExample() {
142
  const [value, setValue] = useState();
143
  return (
144
    <PhoneInput
145
      value={value}
146
      onChange={setValue}
147
      locales={['de', 'fr', 'en']} // Will select best match
148
      defaultCountry="DE"
149
    />
150
  );
151
}
152

153
// Single locale string
154
function SingleLocaleExample() {
155
  const [value, setValue] = useState();
156
  return (
157
    <PhoneInput
158
      value={value}
159
      onChange={setValue}
160
      locales="es"
161
      defaultCountry="ES" 
162
    />
163
  );
164
}
165
```
166

167
### Locale Structure
168

169
Each locale file contains country names and UI element labels.
170

171
```typescript { .api }
172
/**
173
 * Locale file structure
174
 * All entries are optional - missing entries fall back to country codes
175
 */
176
interface LocaleStructure {
177
  // UI element labels
178
  "ext"?: string;      // Extension label (e.g., "ext.")
179
  "country"?: string;  // Country selection aria-label
180
  "phone"?: string;    // Phone input aria-label  
181
  "ZZ"?: string;       // International option label
182
  
183
  // Country name labels (partial list shown)
184
  "US"?: string;       // "United States"
185
  "CA"?: string;       // "Canada"  
186
  "GB"?: string;       // "United Kingdom"
187
  "DE"?: string;       // "Germany"
188
  "FR"?: string;       // "France" 
189
  "JP"?: string;       // "Japan"
190
  "CN"?: string;       // "China"
191
  // ... all ~250 country codes supported
192
}
193
```
194

195
**Example Locale Content:**
196

197
```json
198
{
199
  "ext": "ext.",
200
  "country": "Phone number country", 
201
  "phone": "Phone",
202
  "ZZ": "International",
203
  "US": "United States",
204
  "CA": "Canada",
205
  "GB": "United Kingdom",
206
  "DE": "Germany",
207
  "FR": "France",
208
  "IT": "Italy",
209
  "ES": "Spain",
210
  "JP": "Japan",
211
  "CN": "China",
212
  "IN": "India",
213
  "BR": "Brazil",
214
  "RU": "Russia"
215
}
216
```
217

218
### Custom Labels
219

220
Create custom label objects for specialized use cases or unsupported languages.
221

222
```typescript { .api }
223
/**
224
 * Custom labels interface
225
 * Can override any subset of countries and UI elements
226
 */
227
interface CustomLabels extends Partial<Labels> {
228
  [countryCode: string]: string;
229
}
230

231
// Custom label creation
232
function createCustomLabels(baseLabels: Labels, overrides: Partial<Labels>): Labels {
233
  return { ...baseLabels, ...overrides };
234
}
235
```
236

237
**Custom Labels Examples:**
238

239
```typescript
240
import en from "react-phone-number-input/locale/en.json";
241

242
// Custom UI labels
243
const customUILabels: Labels = {
244
  ...en,
245
  "country": "Select Country",
246
  "phone": "Phone Number", 
247
  "ZZ": "International Number",
248
  "ext": "extension"
249
};
250

251
// Regional customizations
252
const regionalLabels: Labels = {
253
  ...en,
254
  "US": "USA",
255
  "GB": "UK", 
256
  "CN": "Mainland China"
257
};
258

259
// Business-specific labels
260
const businessLabels: Labels = {
261
  ...en,
262
  "US": "United States of America",
263
  "CA": "Canada (requires verification)",
264
  "MX": "Mexico (additional fees apply)"
265
};
266

267
function CustomLabelsExample() {
268
  const [value, setValue] = useState();
269
  return (
270
    <PhoneInput
271
      value={value}
272
      onChange={setValue}
273
      labels={customUILabels}
274
      defaultCountry="US"
275
    />
276
  );
277
}
278
```
279

280
### Locale Loading Strategies
281

282
Different strategies for loading and managing locales in applications.
283

284
```typescript { .api }
285
// Static import strategy
286
import en from "react-phone-number-input/locale/en.json";
287
import de from "react-phone-number-input/locale/de.json";
288
import fr from "react-phone-number-input/locale/fr.json";
289

290
const localeMap = { en, de, fr };
291

292
// Dynamic import strategy
293
async function loadLocale(locale: string): Promise<Labels> {
294
  try {
295
    const module = await import(`react-phone-number-input/locale/${locale}.json`);
296
    return module.default;
297
  } catch (error) {
298
    // Fallback to English
299
    const fallback = await import("react-phone-number-input/locale/en.json");
300
    return fallback.default;
301
  }
302
}
303

304
// Context-based locale management
305
const LocaleContext = React.createContext<Labels>(en);
306
```
307

308
**Dynamic Locale Loading Examples:**
309

310
```typescript
311
import React, { useState, useEffect } from "react";
312
import PhoneInput from "react-phone-number-input";
313

314
// Dynamic locale loading component
315
function DynamicLocalePhoneInput({ locale = "en", ...props }) {
316
  const [labels, setLabels] = useState();
317
  const [loading, setLoading] = useState(true);
318
  
319
  useEffect(() => {
320
    loadLocale(locale)
321
      .then(setLabels)
322
      .finally(() => setLoading(false));
323
  }, [locale]);
324
  
325
  if (loading) return <div>Loading...</div>;
326
  
327
  return (
328
    <PhoneInput
329
      {...props}
330
      labels={labels}
331
    />
332
  );
333
}
334

335
// Locale context provider
336
function LocaleProvider({ locale, children }) {
337
  const [labels, setLabels] = useState();
338
  
339
  useEffect(() => {
340
    loadLocale(locale).then(setLabels);
341
  }, [locale]);
342
  
343
  return (
344
    <LocaleContext.Provider value={labels}>
345
      {children}
346
    </LocaleContext.Provider>
347
  );
348
}
349

350
// Hook for using locale context
351
function useLocale() {
352
  return useContext(LocaleContext);
353
}
354
```
355

356
### RTL Language Support
357

358
The library supports right-to-left languages through proper labeling.
359

360
```typescript { .api }
361
// RTL language examples
362
import ar from "react-phone-number-input/locale/ar.json"; // Arabic
363
import he from "react-phone-number-input/locale/he.json"; // Hebrew
364

365
// RTL usage with proper CSS
366
function RTLExample() {
367
  const [value, setValue] = useState();
368
  return (
369
    <div dir="rtl">
370
      <PhoneInput
371
        value={value}
372
        onChange={setValue}
373
        labels={ar}
374
        defaultCountry="SA"
375
        className="rtl-phone-input"
376
      />
377
    </div>
378
  );
379
}
380
```
381

382
### Locale Fallback Behavior
383

384
The library handles missing locale entries gracefully with fallback behavior.
385

386
```typescript { .api }
387
// Fallback priority order:
388
// 1. Explicit labels prop
389
// 2. Resolved locale from locales prop  
390
// 3. Country code as fallback (e.g., "US" displays as "US")
391
// 4. Default English labels for UI elements
392

393
// Missing country name fallback
394
const incompleteLocale: Labels = {
395
  "ext": "ext.",
396
  "US": "United States",
397
  // "CA" missing - will display as "CA"
398
};
399

400
// UI element fallbacks
401
const countryOnlyLocale: Labels = {
402
  "US": "United States",
403
  "CA": "Canada"
404
  // UI elements missing - will use English defaults
405
};
406
```
407

408
**Fallback Handling Examples:**
409

410
```typescript
411
// Safe locale merging with fallbacks
412
function mergeWithFallbacks(primaryLocale: Labels, fallbackLocale: Labels): Labels {
413
  return {
414
    ...fallbackLocale,
415
    ...primaryLocale
416
  };
417
}
418

419
// Locale with guaranteed UI elements
420
function ensureUILabels(locale: Labels): Labels {
421
  return {
422
    ext: "ext.",
423
    country: "Country", 
424
    phone: "Phone",
425
    ZZ: "International",
426
    ...locale
427
  };
428
}
429

430
// Usage with fallback
431
import en from "react-phone-number-input/locale/en.json";
432
import partialLocale from "./partial-locale.json";
433

434
function FallbackExample() {
435
  const safeLabels = mergeWithFallbacks(partialLocale, en);
436
  
437
  return (
438
    <PhoneInput
439
      labels={safeLabels}
440
      // ... other props
441
    />
442
  );
443
}
444
```