# get-user-locale

> Returns a list of strings representing the user's preferred languages.

Latest version **3.0.0** (published 2025-03-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install get-user-locale
pnpm add get-user-locale
yarn add get-user-locale
bun add get-user-locale
```

## Health

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

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2025-03-20 |
| First published | 2018-08-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 22.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 63 |
| Author | Wojciech Maj |
| Maintainers | wojtekmaj |
| Keywords | locale, language, language-detection |

## Links

- npm: https://www.npmjs.com/package/get-user-locale
- Repository: https://github.com/wojtekmaj/get-user-locale
- Homepage: https://github.com/wojtekmaj/get-user-locale#readme
- Issues: https://github.com/wojtekmaj/get-user-locale/issues
- Funding: https://github.com/wojtekmaj/get-user-locale?sponsor=1
- npm.io page: https://npm.io/package/get-user-locale

## Dependencies (1)

- [memoize](https://npm.io/package/memoize.md) ^10.0.0

## 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

- 3.0.0 (latest) — 2025-03-20
- 2.3.2 — 2024-04-19
- 2.3.1 — 2023-10-18
- 2.3.0 — 2023-07-03
- 2.2.1 — 2023-03-08
- 2.2.0 — 2023-03-02
- 2.1.3 — 2023-02-02
- 2.1.2 — 2023-01-12
- 2.1.1 — 2023-01-11
- 2.1.0 — 2023-01-09
- 2.0.0 — 2022-09-28
- 1.5.1 — 2022-08-04
- 1.5.0 — 2022-07-29
- 1.4.0 — 2020-06-22
- 1.3.0 — 2019-11-03
- … 4 more at https://npm.io/package/get-user-locale/versions

## README

[![npm](https://img.shields.io/npm/v/get-user-locale.svg)](https://www.npmjs.com/package/get-user-locale) ![downloads](https://img.shields.io/npm/dt/get-user-locale.svg) [![CI](https://github.com/wojtekmaj/get-user-locale/actions/workflows/ci.yml/badge.svg)](https://github.com/wojtekmaj/get-user-locale/actions)

# Get-User-Locale

A function that returns user's locale as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag), based on all available sources.

## tl;dr

- Install by executing `npm install get-user-locale` or `yarn add get-user-locale`.
- Import by adding `import getUserLocale from 'get-user-locale'`.
- Do stuff with it!
  ```ts
  const userLocale = getUserLocale();
  ```

## User guide

### `getUserLocale()`

A function that returns user's preferred locale as an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag), based on all available sources.

#### Sample usage

```ts
import getUserLocale from 'get-user-locale';

getUserLocale(); // 'de-DE'
```

or

```ts
import { getUserLocale } from 'get-user-locale';

getUserLocale(); // 'de-DE'
```

##### Options

`getUserLocale()` may be called with an optional `options` argument.

`options` object may contain the following properties:

| Property            | Description                         | Default value |
| ------------------- | ----------------------------------- | ------------- |
| `fallbackLocale`    | A locale to use as a fallback.      | `en-US`       |
| `useFallbackLocale` | Whether to use the fallback locale. | `true`        |

### `getUserLocales()`

A function that returns an array of user's preferred locales as an [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag), based on all available sources.

#### Sample usage

```ts
import { getUserLocales } from 'get-user-locale';

getUserLocales(); // ['de-DE', 'de', 'en-US', 'en']
```

##### Options

`getUserLocales()` may be called with an optional `options` argument.

`options` object may contain the following properties:

| Property            | Description                         | Default value |
| ------------------- | ----------------------------------- | ------------- |
| `fallbackLocale`    | A locale to use as a fallback.      | `en-US`       |
| `useFallbackLocale` | Whether to use the fallback locale. | `true`        |

## Technical details

There are a few ways of determining user's locale:

- `window.navigator.languages`
- `window.navigator.language`

`…languages` is an array of strings, `…language` is a string. Some browsers return mixed-case [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) (e.g. `de-DE`), while others return lowercase ones (e.g. `de-de`). Finally, non-browser environments will not return anything, so you need a fallback.

Get-User-Locale does the following:

- Combines all of them into one sane set of locales - in that particular order,
- Dedupes them,
- Fixes invalid, lowercased [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) (so that the part after `-` is always uppercased),
- Adds a fallback to `en-US`, so if all else fails, you will get a result that won't crash your app.

## License

The MIT License.

## Author

<table>
  <tr>
    <td >
      <img src="https://avatars.githubusercontent.com/u/5426427?v=4&s=128" width="64" height="64" alt="Wojciech Maj">
    </td>
    <td>
      <a href="https://github.com/wojtekmaj">Wojciech Maj</a>
    </td>
  </tr>
</table>

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