or run

npx @tessl/cli init
Log in

Version

Files

tile.json

tessl/npm-os-locale

Cross-platform utility library for detecting and retrieving the system locale from the operating system

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/os-locale@6.0.x

To install, run

npx @tessl/cli install tessl/npm-os-locale@6.0.0

index.mddocs/

OS Locale

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.

Package Information

  • Package Name: os-locale
  • Package Type: npm
  • Language: JavaScript (ES modules with TypeScript definitions)
  • Installation: npm install os-locale

Core Imports

import { osLocale, osLocaleSync } from "os-locale";

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

const { osLocale, osLocaleSync } = await import("os-locale");

Basic Usage

import { osLocale, osLocaleSync } from "os-locale";

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

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

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

Capabilities

Asynchronous Locale Detection

Gets the system locale asynchronously with optimal performance.

/**
 * Get the system locale asynchronously
 * @param options - Configuration options for locale detection
 * @returns Promise resolving to the locale string (e.g., 'en-US')
 * @example
 * ```
 * import {osLocale} from 'os-locale';
 * 
 * console.log(await osLocale());
 * //=> 'en-US'
 * ```
 */
function osLocale(options?: Options): Promise<string>;

Usage Examples:

import { osLocale } from "os-locale";

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

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

Synchronous Locale Detection

Gets the system locale synchronously for simpler code patterns.

/**
 * Get the system locale synchronously
 * @param options - Configuration options for locale detection
 * @returns The locale string (e.g., 'en-US')
 * @example
 * ```
 * import {osLocaleSync} from 'os-locale';
 * 
 * console.log(osLocaleSync());
 * //=> 'en-US'
 * ```
 */
function osLocaleSync(options?: Options): string;

Usage Examples:

import { osLocaleSync } from "os-locale";

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

// Environment variables only (synchronous)
const envLocale = osLocaleSync({ spawn: false });
console.log(envLocale); // Locale from environment variables

Types

interface Options {
  /**
   * Set to `false` to avoid spawning subprocesses and instead only resolve the locale from environment variables.
   * 
   * @default true
   */
  readonly spawn?: boolean;
}

Platform Support

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

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

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

Error Handling

Both functions handle errors gracefully:

  • If locale detection fails, returns 'en-US' as the default locale
  • No exceptions are thrown - the functions always return a valid locale string
  • Subprocess execution errors are caught and handled silently

Performance

The library includes internal caching based on the spawn option to avoid repeated system calls:

  • Results are cached using a Map with the spawn option as the key
  • Subsequent calls with the same options return cached results
  • Cache improves performance for applications that check locale multiple times