0
# OS Locale
1

2
OS Locale is a cross-platform utility library for detecting and retrieving the system locale (language and region settings) from the operating system. It provides both asynchronous and synchronous APIs to access locale information by examining environment variables and executing system-specific commands when needed.
3

4
## Package Information
5

6
- **Package Name**: os-locale
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules with TypeScript definitions)
9
- **Installation**: `npm install os-locale`
10

11
## Core Imports
12

13
```javascript
14
import { osLocale, osLocaleSync } from "os-locale";
15
```
16

17
For CommonJS (requires dynamic import since this is an ES module):
18

19
```javascript
20
const { osLocale, osLocaleSync } = await import("os-locale");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { osLocale, osLocaleSync } from "os-locale";
27

28
// Asynchronous (recommended)
29
const locale = await osLocale();
30
console.log(locale); // 'en-US'
31

32
// Synchronous
33
const localeSync = osLocaleSync();
34
console.log(localeSync); // 'en-US'
35

36
// With options
37
const envOnlyLocale = await osLocale({ spawn: false });
38
console.log(envOnlyLocale); // Locale from environment variables only
39
```
40

41
## Capabilities
42

43
### Asynchronous Locale Detection
44

45
Gets the system locale asynchronously with optimal performance.
46

47
```javascript { .api }
48
/**
49
 * Get the system locale asynchronously
50
 * @param options - Configuration options for locale detection
51
 * @returns Promise resolving to the locale string (e.g., 'en-US')
52
 * @example
53
 * ```
54
 * import {osLocale} from 'os-locale';
55
 * 
56
 * console.log(await osLocale());
57
 * //=> 'en-US'
58
 * ```
59
 */
60
function osLocale(options?: Options): Promise<string>;
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
import { osLocale } from "os-locale";
67

68
// Default behavior (checks environment variables and spawns system commands)
69
const locale = await osLocale();
70
console.log(locale); // 'en-US', 'fr-FR', 'ja-JP', etc.
71

72
// Environment variables only (no subprocess spawning)
73
const envLocale = await osLocale({ spawn: false });
74
console.log(envLocale); // Locale from LC_ALL, LC_MESSAGES, LANG, or LANGUAGE
75
```
76

77
### Synchronous Locale Detection
78

79
Gets the system locale synchronously for simpler code patterns.
80

81
```javascript { .api }
82
/**
83
 * Get the system locale synchronously
84
 * @param options - Configuration options for locale detection
85
 * @returns The locale string (e.g., 'en-US')
86
 * @example
87
 * ```
88
 * import {osLocaleSync} from 'os-locale';
89
 * 
90
 * console.log(osLocaleSync());
91
 * //=> 'en-US'
92
 * ```
93
 */
94
function osLocaleSync(options?: Options): string;
95
```
96

97
**Usage Examples:**
98

99
```javascript
100
import { osLocaleSync } from "os-locale";
101

102
// Default synchronous behavior
103
const locale = osLocaleSync();
104
console.log(locale); // 'en-US'
105

106
// Environment variables only (synchronous)
107
const envLocale = osLocaleSync({ spawn: false });
108
console.log(envLocale); // Locale from environment variables
109
```
110

111
## Types
112

113
```typescript { .api }
114
interface Options {
115
  /**
116
   * Set to `false` to avoid spawning subprocesses and instead only resolve the locale from environment variables.
117
   * 
118
   * @default true
119
   */
120
  readonly spawn?: boolean;
121
}
122
```
123

124
## Platform Support
125

126
The library works across different operating systems with platform-specific detection methods:
127

128
- **Windows**: Uses `wmic os get locale` command to get LCID, then converts to locale using the `lcid` package
129
- **macOS**: Uses `defaults read -globalDomain AppleLocale` command to get system locale
130
- **Linux/Unix**: Uses `locale` command to parse system locale configuration
131
- **All Platforms**: Falls back to environment variables (`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`)
132

133
When `spawn: false` is set, only environment variables are checked, providing faster execution at the cost of reduced accuracy on some systems.
134

135
## Error Handling
136

137
Both functions handle errors gracefully:
138
- If locale detection fails, returns `'en-US'` as the default locale
139
- No exceptions are thrown - the functions always return a valid locale string
140
- Subprocess execution errors are caught and handled silently
141

142
## Performance
143

144
The library includes internal caching based on the `spawn` option to avoid repeated system calls:
145
- Results are cached using a Map with the spawn option as the key
146
- Subsequent calls with the same options return cached results
147
- Cache improves performance for applications that check locale multiple times