web-locale-kit

web-locale-kit

A tiny TypeScript locale detector — resolves the user's language(s), timezone, UTC offset, and text direction (RTL/LTR) from Intl and navigator, with tag normalization and graceful fallbacks.

npm install web-locale-kit

API at a glance

LocaleKit is a singleton. All fields are read-only and resolved once at import.

Member	Type	Description
LocaleKit.version	string	The installed package version
LocaleKit.language	string | null	Primary normalized BCP-47 tag (e.g. "ko-KR"), or null if undetectable
LocaleKit.languages	readonly string[]	All detected tags, de-duplicated and normalized, in preference order
LocaleKit.timezone	string | null	IANA timezone (e.g. "Asia/Seoul"), or null
LocaleKit.offset	number	Minutes ahead of UTC (e.g. Seoul → 540; opposite sign of getTimezoneOffset())
LocaleKit.rtl	boolean	Whether the primary language is right-to-left

---

ESM

import LocaleKit from 'web-locale-kit'

console.log(LocaleKit.language)  // "ko-KR"
console.log(LocaleKit.languages) // ["ko-KR", "en-US"]
console.log(LocaleKit.timezone)  // "Asia/Seoul"
console.log(LocaleKit.offset)    // 540  (UTC+9, in minutes)
console.log(LocaleKit.rtl)       // false

document.documentElement.dir = LocaleKit.rtl ? 'rtl' : 'ltr'

CommonJS

The bundle is built with exports: "named", so the singleton lives under .default:

const { default: LocaleKit } = require('web-locale-kit')

console.log(LocaleKit.language, LocaleKit.timezone)

UMD (browser <script>)

The global LocaleKit is a namespace object; the singleton is LocaleKit.default.

<script src="https://unpkg.com/web-locale-kit/dist/locale-kit.umd.min.js"></script>
<script>
    var locale = window.LocaleKit.default

    document.documentElement.lang = locale.language || 'en'
    document.documentElement.dir = locale.rtl ? 'rtl' : 'ltr'
</script>

TypeScript

The singleton shape is exported as LocaleKitInstance.

import LocaleKit, { type LocaleKitInstance } from 'web-locale-kit'

const lang: string | null = LocaleKit.language
const isRTL: boolean = LocaleKit.rtl

---

Notes

• Resolved once at import. Values are computed when the module loads; they do not update if the user changes language or timezone mid-session. Re-evaluate by reloading, or read again on navigation if your app supports live locale switches.
• offset is inverted vs getTimezoneOffset(). Standard JS returns minutes behind UTC (Seoul → -540); this field flips the sign so positive means ahead of UTC (Seoul → 540), which reads more intuitively.
• language / timezone may be null in environments without Intl or navigator (e.g. some server/Node contexts). Guard before use.
• RTL detection prefers Intl.Locale.prototype.getTextInfo() where available, falling back to a curated list of RTL language subtags.