regionist

Guess regional parameters of your users in a most reliable way.

Usage no npm install needed!

<script type="module">
  import regionist from 'https://cdn.skypack.dev/regionist';
</script>

README

regionist

Guess regional parameters of your users in a most reliable way.

NPM npm version npm bundle size npm

In browsers, there is no bullet-proof way to find user's region, language or other local parameters without asking. This module built for to make best guess about these local parameters. It relies on:

  1. window.Intl object with fallback to the good old timezone detection library jstz.
  2. The browser's navigator object.

Here is what you get after a successful guess:

{
  timezone: 'Europe/Istanbul',
  country: 'TR',
  nativeLanguage: 'tr',
  preferredLanguage: 'en',
  locale: 'tr_TR',
  currencyCode: 'TRY',
  callingCode: '90'
}

Install

npm i regionist

Import

There are exports for es6, cjs and umd environments:

// cjs
const {regionist} = require('regionist')

// or es
import {regionist} from 'regionist'

or inject via script tag:

<script src="https://cdn.jsdelivr.net/npm/regionist@3/dist/browser/iife/index.js" type="text/javascript"></script>

You can access it via global window.regionist when import it via script tag.

Usage

Just do:

const result = regionist.guess()

// result
{
  timezone: 'Europe/Istanbul',
  country: 'TR',
  nativeLanguage: 'tr',
  preferredLanguage: 'en',
  locale: 'tr_TR',
  currencyCode: 'TRY',
  callingCode: '90'
}

Note that result is an instance of Regionist. So you can call another methods.

Check If User Timezone Have Changed

Store user parameters in local storage:

const result = regionist.guess({remember: true/*false by default*/})

When user revisited the page some time later, execute compare function:

const result = regionist.guess({remember: true})
result.isTimezoneChanged() // returns boolean

Pick Language or Locale From A List

Regionist can pick the most suitable language/locale for the user from a given list:

const result = regionist.guess()

const appSupportedLocales = ['en_US', 'tr_TR']
const userAppLocale = result.pick(appSupportedLocales)

It returns the first item of the input list at the worst case.

Locale Data

Country - language - phone number - currency mappings provided by locale-util package. You can actually use them by importing:

import {currencyCodes, callingCodes, countryLanguages, timezones} from 'regionist'

Timezone Detection

For timezone detection an excellent jstz library have been used.

Version management of this repository done by releaser 🚀

Thanks for watching 🐬

ko-fi