# match-supported-locale

> A small, zero-dependency, TypeScript-compatible utility for best-matching a locale against a list of supported locales.

Latest version **1.1.0** (published 2026-03-09) · ISC license · 0 weekly downloads

## Install

```sh
npm install match-supported-locale
pnpm add match-supported-locale
yarn add match-supported-locale
bun add match-supported-locale
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-03-09 |
| First published | 2022-07-30 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 17.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | floog9 |
| Keywords | locale, match locale, match supported locale, best-match supported locale |

## Links

- npm: https://www.npmjs.com/package/match-supported-locale
- Homepage: https://github.com/DavidR95/match-supported-locale#readme
- npm.io page: https://npm.io/package/match-supported-locale

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-03-09
- 1.0.0 — 2022-07-30

## README

# Match Supported Locale

A small, zero-dependency, TypeScript-compatible utility for best-matching a locale against a list of supported locales.

## Installation

```bash
npm install match-supported-locale
```

## Usage

```typescript
import { matchSupportedLocale } from 'match-supported-locale';

matchSupportedLocale('zh-Hans-HK', ['en', 'zh-Hans', 'fr-FR']); // = 'zh-Hans'
matchSupportedLocale('en-US', ['en', 'zh-Hans', 'fr-FR']); // = 'en'
matchSupportedLocale('zh-Hant', ['en', 'zh-Hans', 'fr-FR'], {
  zh: 'zh-Hans',
}); // = 'zh-Hans' (with optional language locale fallback)
```

### Options

- `locale: string`

  The locale to find a best-match against. Usually taken from `navigator.language`.

- `supportedLocales: string[]`

  The list of locales your application supports.

- `languageLocaleFallbacks?: Record<string, string>`

  Optional. Allows specifying language-wide fallbacks when no direct matches can be found. For example:

  ```typescript
  matchSupportedLocale('en-US', ['en-GB', 'en-NZ'], {
    en: 'en-GB',
  }); // = 'en-GB'
  ```

## More Details & Real Examples

This will mostly be useful when trying to set the initial language of an internalization plugin - where you want to restrict that value to a list of officially supported languages.

Usually this initial language will be derived from `navigator.language` when running in a browser environment, but this value can be unpredictable depending on the device/browser.

If your application specifically supports `zh-Hans`, you'll likely want to use that locale regardless of whether `navigator.language` returns `zh`, `zh-Hans` or `zh-Hans-HK`.

```typescript
const defaultLocale = 'en-US';

const supportedLocales = ['en-GB', 'en-US', 'fr-FR', 'de-DE', 'de-LI'];

const locale =
  matchSupportedLocale(navigator.language, supportedLocales, {
    en: 'en-GB',
    fr: 'fr-FR',
    de: 'de-DE',
  }) ?? defaultLocale;
```

Using the code above, `locale` can now be passed to your internalization plugin with confidence that it is definitely one of your supported locales, and that it has matched as closely as it can.

---
_Source: https://npm.io/package/match-supported-locale · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._