https://github.com/wopian/preferred-locale
🎌 Get a users' preferred locale/language from your app's available translations
https://github.com/wopian/preferred-locale
browser browser-languages country intl javascript javascript-library lang language language-detection locale localisation localization node region translations typescript
Last synced: 22 days ago
JSON representation
🎌 Get a users' preferred locale/language from your app's available translations
- Host: GitHub
- URL: https://github.com/wopian/preferred-locale
- Owner: wopian
- License: mit
- Created: 2020-07-13T01:40:19.000Z (almost 5 years ago)
- Default Branch: develop
- Last Pushed: 2025-04-09T19:44:01.000Z (24 days ago)
- Last Synced: 2025-04-11T20:07:02.428Z (22 days ago)
- Topics: browser, browser-languages, country, intl, javascript, javascript-library, lang, language, language-detection, locale, localisation, localization, node, region, translations, typescript
- Language: TypeScript
- Homepage: https://yarn.fyi/preferred-locale
- Size: 14.2 MB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Preferred Locale
🎌 Get the users' most preferred locale/language from your app's available translations with zero dependencies
#
## Features
- Uses the Intl.Locale API (backwards compatible)
- Works on node & browsers
- Zero dependencies
- TypeScript support
## Usage
This library is fully typed with TSDoc examples. View the online documentation here: https://wopian.github.io/preferred-locale/
```ts
import { preferredLocale } from 'preferred-locale'
// Note: All examples assume the browser's reported locales are:
// [ 'en-GB', 'en', 'ja-JP', 'en-US', 'ja' ]
const supportedLocales = ['en-US', 'ja-JP']
const fallbackLocale = 'ja-JP'
const locale = preferredLocale(supportedLocales, fallbackLocale)
console.log(locale) // 'en-US', converts 'en-GB' and 'en' to 'en-US' as neither are translated, placing it before 'ja-JP' in preference order
preferredLocale(['en-us', 'fr-fr'], ['en-us'], {
regionLowerCase: true
}) // 'en-us', converts 'en-GB' to 'en-us' as 'en-gb' is not translated
preferredLocale(['de', 'fr'], ['fr'], {
languageOnly: true
}) // 'fr', converts 'en-GB' to 'en' (etc). No matching locales so returns 'fr' fallback
preferredLocale(['en-US', 'en-GB'], ['en-US']) // 'en-GB', as it is translated and first in user's preference order
```
## Guaranteed Node / Browser Support
| Package | Package
Size | Node | Chrome | Firefox | Safari | Edge |
| -----------------: | :-------------: | :--: | :----: | :-----: | :----: | :--: |
| `preferred-locale` | ~600 bytes | 14+ | 69+ | 68+ | 12+ | 18+ |
`preferred-locale@2` is a rewrite of `preferred-locale@1`, written in TypeScript as a native ESM module. If your environment does not support ESM modules, you can continue to use `preferred-locale@1` as the resultant code is identical.
## Why?
Many web applications that automatically detect the browser language and serve the relevent translation are fundamentally broken.
A browser that signals the user prefers the following locales (index `0` being most preferred) should _never_ return content in Japanese (`ja-JP`) if the application has translations for Japanese and American English (`en-US`):
- `[ 'en-GB', 'en', 'ja-JP', 'en-US', 'ja' ]`
Instead, many applications (e.g Epic Games' store, help and documentation) will instead serve their users content in Japanese as they do not provide translations for British English, only American English and only check for exact matches.
`preferred-locale` fixes this by traversing the supported node/browser languages in order of priority:
1. If an exact match is found it uses that (e.g `en-GB` is translated).
2. If the node/browser language is supported but the region is not (e.g Australian English), the canonical region is looked up and tested against (e.g `en-AU` becomes `en-US`),
3. If only a language is provided (e.g `en`), the canonical region is looked up and tested against (e.g `en` becomes `en-US`)
4. If no node/browser locale resolves to a translated locale, the fallback locale is returned
### Live Demo
A step-by-step demonstration of how `preferred-locale@1` works with your own browser locales is available at [eehz9.csb.app](https://eehz9.csb.app).
### Example Step-By-Step
Application has translations for `en-US` and `ja-JP`
1. Raw browser locales `[ 'en-GB', 'en', 'ja-JP', 'en-US', 'ja' ]`
2. Unify the browser locales `[ 'en-GB', 'en-US', 'ja-JP', 'en-US', 'ja-JP' ]`
3. Deduplicate the locales `[ 'en-GB', 'en-US', 'ja-JP' ]`
4. Remove locales not translated `[ 'en-US', 'ja-JP' ]`
5. User gets content in `en-US`
## Contributing
See [CONTRIBUTING]
## Releases
See [Github Releases]
## License
All code released under [MIT]
[preferred-locale]: https://github.com/wopian/preferred-locale/tree/master/packages/preferred-locale
[github releases]: https://github.com/wopian/preferred-locale/releases
[contributing]: https://github.com/wopian/preferred-locale/blob/master/CONTRIBUTING.md
[mit]: https://github.com/wopian/preferred-locale/blob/master/LICENSE.md
```
```
```
```