0
# Language Matching
1

2
Intelligent language tag matching to find the best supported language from your app's available translations based on device locale preferences.
3

4
## Capabilities
5

6
### Find Best Language Tag
7

8
Finds the best matching language tag from a provided list based on the device's locale preferences. Uses intelligent matching that considers language-country combinations, language-script combinations, and language-only fallbacks.
9

10
```typescript { .api }
11
/**
12
 * Find the best matching language tag from provided options
13
 * @param languageTags - Array of supported language tags in your app
14
 * @returns Object with matched language tag and RTL flag, or undefined if no match
15
 */
16
function findBestLanguageTag<T extends string>(
17
  languageTags: ReadonlyArray<T>
18
): { languageTag: T; isRTL: boolean } | undefined;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { findBestLanguageTag } from "react-native-localize";
25

26
// Basic language matching
27
const supportedLanguages = ["en-US", "fr-FR", "es-ES", "de-DE"];
28
const bestMatch = findBestLanguageTag(supportedLanguages);
29

30
if (bestMatch) {
31
  console.log(`Selected language: ${bestMatch.languageTag}`);
32
  console.log(`Is RTL: ${bestMatch.isRTL}`);
33
  // Use this language for your app's localization
34
} else {
35
  console.log("No matching language found, using default");
36
  // Fall back to default language
37
}
38
```
39

40
**Advanced Usage:**
41

42
```typescript
43
import { findBestLanguageTag } from "react-native-localize";
44

45
// App with multiple language variants
46
const supportedLanguages = [
47
  "en-US",    // American English
48
  "en-GB",    // British English
49
  "fr-FR",    // French (France)
50
  "fr-CA",    // French (Canada)
51
  "es-ES",    // Spanish (Spain)
52
  "es-MX",    // Spanish (Mexico)
53
  "ar-SA",    // Arabic (Saudi Arabia)
54
  "he-IL"     // Hebrew (Israel)
55
];
56

57
const match = findBestLanguageTag(supportedLanguages);
58

59
if (match) {
60
  // Configure app language
61
  setAppLanguage(match.languageTag);
62
  
63
  // Configure layout direction
64
  if (match.isRTL) {
65
    setLayoutDirection('rtl');
66
  } else {
67
    setLayoutDirection('ltr');
68
  }
69
}
70

71
// Usage with fallback strategy
72
function selectAppLanguage(supportedLanguages: string[]) {
73
  // Try exact matching first
74
  let match = findBestLanguageTag(supportedLanguages);
75
  
76
  if (!match && supportedLanguages.includes("en")) {
77
    // Fall back to English if available
78
    match = { languageTag: "en" as any, isRTL: false };
79
  }
80
  
81
  return match?.languageTag || "en";
82
}
83
```
84

85
**Integration with i18n Libraries:**
86

87
```typescript
88
import { findBestLanguageTag } from "react-native-localize";
89
import i18n from "i18next";
90

91
// Configure i18next based on device preferences
92
const supportedLanguages = Object.keys(i18n.options.resources || {});
93
const bestLanguage = findBestLanguageTag(supportedLanguages);
94

95
if (bestLanguage) {
96
  i18n.changeLanguage(bestLanguage.languageTag);
97
}
98

99
// React Native usage with React Navigation
100
import { findBestLanguageTag } from "react-native-localize";
101

102
function configureApp() {
103
  const supportedLanguages = ["en", "es", "fr", "de", "ar", "he"];
104
  const match = findBestLanguageTag(supportedLanguages);
105
  
106
  if (match) {
107
    // Set app language
108
    setI18nLanguage(match.languageTag);
109
    
110
    // Configure navigation for RTL languages
111
    if (match.isRTL) {
112
      // Enable RTL support in navigation
113
      NavigationContainer.setRTL(true);
114
    }
115
  }
116
}
117
```
118

119
## Matching Algorithm
120

121
The `findBestLanguageTag` function uses a sophisticated matching algorithm:
122

123
1. **Exact Match**: First tries to match the complete language tag (e.g., "en-US")
124
2. **Language-Script Match**: Matches language with script code (e.g., "zh-Hans")
125
3. **Language-Country Match**: Matches language with country (e.g., "en-US" matches "en-GB")
126
4. **Language-Only Match**: Falls back to language code only (e.g., "en")
127

128
The function processes device locales in order of preference, ensuring the best possible match for the user's language preferences.