LocaleSmart selects the best locale from browser preferences and (optionally) GEO, maps it to a short code (e.g., ru or a market code), and applies it to the document. It supports market definitions, URL overrides, and a customizable mapping function from a full tag to a short code.

^{1.5kB gzipped}

➠ Install

yarn add locale-smart

➠ Import

import LocaleSmart from 'locale-smart';

➠ Usage

// Basic usage: resolve a locale and update the document
const resolver = new LocaleSmart();
resolver.init();
// Adds a class like "locale-ru" to <body> and sets <html lang="ru">

_{Initialization with options}

// Define markets with codes, tags, and GEO mapping
const resolver = new LocaleSmart({
  locales: [
    { code: 'RU', tag: 'ru-RU', geos: ['RU'] },
    { code: 'BY', tag: 'ru-BY', geos: ['BY'] },
    { code: 'EN', tag: 'en-US', geos: ['US', 'GB'] },
  ],
  defaultCode: 'RU',
  getGeo: () => window.myGeoCode, // e.g., 'BY'
  classPrefix: 'locale-',
});

resolver.init();
// When `locales` is provided, the short code defaults to the market `code`
// e.g., with GEO=BY the <body> gets class "locale-BY"

_{URL override}

// If the URL contains ?locale=en or ?locale=en-US or ?locale=BY,
// it takes precedence and is applied immediately
new LocaleSmart().init();
// You can also read/apply it manually with a different parameter name:
const r = new LocaleSmart();
r.applyOverrideFromUrl('lang');

_{Server-side / no DOM}

// Determine a short locale without touching the DOM
const r = new LocaleSmart({ documentRef: null });
const short = r.determineShortLocale(); // e.g., 'ru'

➠ Options

Option	Type	Default	Description
`locales`	`ReadonlyArray<{ code: string; tag: string; geos?: readonly string[] }>`	`undefined`	Defines markets. Enables code↔tag mapping and GEO resolution. When set, supported locales are derived from this list.
`defaultCode`	`string`	first of `locales`	Default market code when `locales` is provided.
`supported`	`readonly string[]`	`["ru-RU"]`	Supported locale tags when `locales` is not provided.
`defaultLocale`	`string`	`"ru-RU"`	Default locale tag when `locales` is not provided.
`getGeo`	`() => string \| undefined`	`undefined`	Returns GEO/market code (e.g., `RU`, `BY`) used as a hint during resolution.
`getRequestedLocales`	`() => readonly string[]`	`navigator.languages`	Provides the requested locales list; falls back to `navigator.language`.
`documentRef`	`Document`	global `document` or `null`	Custom document object; set `null` to disable DOM updates.
`geoMap`	`Readonly<Record<string, string>>`	`undefined`	Map `GEO_CODE -> localeTag`. Used when `getGeo()` returns a code.
`classPrefix`	`string`	`"locale-"`	Prefix for the class applied to `<body>`, e.g., `locale-ru`.
`shortFromTag`	`(tag: string) => string`	market code from `locales` or `tag.split('-')[0]`	Maps a full locale tag to a short code. Overridable.

➠ API Methods

Method	Description
`init(): string`	Resolves the short locale and applies it to the document. Honors URL override. Returns the short code.
`determineShortLocale(): string`	Resolves and stores the short locale without touching the DOM.
`applyToDocument(short: string): void`	Applies `classPrefix + short` to `<body>` and sets `<html lang>`.
`applyOverrideFromUrl(paramName = 'locale'): string \| undefined`	Reads the query parameter and, if a match is found (by full tag, market code, or short), applies the locale.
`currentLocale: string` (getter)	Returns the currently resolved short locale.

➠ Notes

Resolution order: URL override, then GEO hint, then browser preferences; finally the default value.
If Intl.LocaleMatcher.bestFit is available, it is used; otherwise, a language-prefix strategy with a default fallback is applied.

➠ License

locale-smart is released under MIT license

Keywords

FAQs

What is locale-smart?

Is locale-smart well maintained?

Package last updated on 22 Oct 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

locale-smart

Keywords

Related posts

Feross on TBPN: How North Korea Hijacked Axios

Attackers Are Impersonating a Linux Foundation Leader in Slack to Target Open Source Developers