OS locale detector (os-locale-s)

Compatibility-first locale detector for mixed and legacy-like environments.

Get the system locale

Useful for localizing your module or app.

POSIX systems: The returned locale refers to the LC_MESSAGE category, suitable for selecting the language used in the user interface for message translation.

Motivation (Legacy Context)

Originally, this package was created as a lightweight rewrite for simple locale detection. That historical reason still matters, but the project now has its own direction.

Project Position (2026)

os-locale and os-locale-s are no longer trying to be the same thing. os-locale-s focuses on compatibility-first behavior for real-world environments, including restricted or legacy-like setups.

If your runtime is modern and up to date, check os-locale first. Recent upstream implementations are very lightweight and may already be the best default choice.

Use os-locale-s when you need legacy-friendly behavior, stricter fallback handling, or env-first control in mixed environments.

Legacy-Friendly Behavior

• Environment-first detection via LC_ALL, LC_MESSAGES, LANG, LANGUAGE
• spawn: false mode for environments where subprocess execution is restricted
• Platform detectors when spawning is enabled
• Windows: PowerShell locale name
• macOS: defaults + locale -a
• Linux/Unix: locale
• Safe fallback to en_US if commands fail

Install

$ npm install os-locale-s

Usage

// node (commenjs)
const { osLocale } = require("os-locale-s");
(async () => {
    console.log(await osLocale());
    //=> 'en-US'
})();

// ECMA module
import { osLocale } from "os-locale-s";
(async () => {
    console.log(await osLocale());
    //=> 'en-US'
})();

API

osLocale(options?)

Returns a Promise for the locale.

osLocale.sync(options?)

Returns the locale.

options

Type: object

spawn

Type: boolean
Default: true

Set to false to avoid spawning subprocesses and instead only resolve the locale from environment variables. (process.env)

cache

Type: boolean
Default: true

Once the locale is detected, its value is retained and reused at the second and subsequent detections.

If set to false, the last held value will be ignored and do locale detection again (and the resulting value is not preserved)